home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / mxlibs / dwstk102 / stkman.doc < prev    next >
Text File  |  1995-04-18  |  94KB  |  2,671 lines
  1.                 DiamondWare's Sound ToolKit
  2.  
  3. Welcome to DiamondWare's Sound ToolKit (STK).  If you're a game or
  4. multimedia developer or programmer, and you want a hassle-free, easy
  5. way to include high-quality music and digitized sound effects in
  6. your products, and you don't want to pay high licensing fees or
  7. ongoing royalties, you've come to the right place.
  8.  
  9. My name is Dave Snyder, and I'm the President of MVP Software.  I'd
  10. like to tell you a little about this product and why we're so
  11. excited about it.
  12.  
  13. Q: Why is MVP Software Publishing a Programmer's Toolkit?  I thought
  14. you guys published games?
  15.  
  16. MVP is indeed a game publisher.  As such, we are always on the
  17. lookout for ways to make our games better.  Frankly, until now we
  18. had never found any sound drivers with which we were happy.
  19. Although we've tried most of them, and used some of them, there were
  20. always problems.
  21.  
  22. For one thing, I don't want our games littering users' hard drives
  23. with zillions of tiny files.  For another, I want our games to work.
  24. Period.  I want them to work with all the sound cards out there.  I
  25. want our games to work on IRQs 2, 7, and 10, the notorious "problem"
  26. IRQs.  I want the sound card setup to be completely transparent to
  27. my users.  Many of our users don't even know what sound cards they
  28. have installed in their systems, let alone what IRQ or DMA it's
  29. installed on.  I want our sound drivers to handle all that stuff
  30. reliably and automatically.
  31.  
  32. In addition, I want our games to sound great.  I want haunting
  33. melodies, growling sound effects, and realistic reproduction.  I
  34. don't want the sound drivers to take much memory, and I definitely
  35. don't want them to sap speed from our games.  I want our DOS games
  36. to work in a Windows or OS/2 DOS box.
  37.  
  38. One other thing.  I don't want MVP programmers to take all their
  39. time learning how to use sound drivers.  I want the API to be clean
  40. and the implementation as painless as possible.  And I want the
  41. sound drivers to work fine in C/C++, Assembly, Pascal, and BASIC.
  42.  
  43. Q: It sounds like you want a miracle!
  44.  
  45. Yep, and that's why we're publishing DiamondWare's Sound ToolKit.
  46. This product does all these things and more.  We've begun
  47. implementing it in our games.  Already we have implemented it in
  48. games written in C, Pascal, and BASIC.  We've conducted user beta
  49. tests of these games.  In fact, we were so pleased with its
  50. performance that we arranged to publish it and make it available to
  51. other developers.
  52.  
  53. So if you want great sound in your games, you want easy
  54. implementation, and you want to produce a game even a Kmart shopper
  55. can install and use without calling tech support, give DiamondWare's
  56. Sound Toolkit a run for its money.
  57.  
  58. Q: Can I try out DiamondWare's Sound ToolKit before I buy it?  I want
  59. to see for myself that everything you say about it is true!
  60.  
  61. You bet.  That's why we have released this fully-functional demo.
  62. You have everything you need right now to implement the STK in your
  63. game or application and put it through its paces.  All the functions
  64. and functionality is included in this demo.  We're so sure that
  65. after you try this you'll want the full product, that we're not
  66. hiding anything!  Heck, our docs even describe its limitations.
  67.  
  68. We only ask two things.  First, try the STK for 30 days.  If you
  69. like it, buy the full DiamondWare's Sound ToolKit directly from MVP.
  70. The price is only $299.95, and there are no additional fees or
  71. royalties to pay.  You get unlimited technical support too.  Second,
  72. tell your programmer friends about the STK and give them this demo.
  73.  
  74. Q: When I buy the full STK, what do I get?
  75.  
  76. Well, first of all, you get the complete product without those
  77. beginning and ending sound effects that you hear in this demo.  We
  78. know you're honest, but we weren't sure about everyone else. <g>
  79. Seriously, this is a demo, not a free toolkit, and we put those
  80. sound effects in there so everyone knows that right away.  So when
  81. you purchase the full STK, you get a fully useable product.
  82.  
  83. Second, you get an excellent printed manual.  Our manual is the best
  84. sound toolkit manual there is.  We've included full file
  85. specifications on our .dwd and .dwm file formats.  We've even
  86. included a chapter on aesthetic and design considerations of music
  87. and sound in games, written by a published professional musician in
  88. the field.
  89.  
  90. Third, you get an extra .ibk file.
  91.  
  92. Fourth, you get $287 of bundled software.  Yep, that's right, you
  93. pay us $299.95 for the STK, and we include not only the STK drivers,
  94. the docs, and the extra .ibk file, but we include $287 of additional
  95. software.
  96.  
  97. Q: Cool!  What extra software do I get?
  98.  
  99. Well, if you're serious about music and sound effects in your
  100. product, you'll need a FM editor and a digitized sound editor.
  101. We've bundled two of the best with the STK, Flashpoint Production's
  102. Symphonix OPL FM Patch Editor and Sonic Foundry's Sound Forge 2.0.
  103. And these aren't shareware versions or demos, but full retail
  104. products, including their own manuals.  Both are Windows programs,
  105. and if you were to buy them separately (both are widely available),
  106. you would spend $218.90 for the software.
  107.  
  108. But that's not all.  When you purchase the full STK, you also
  109. receive a CD of 300 sound effects.  This CD has a list price of
  110. $69.95.  The sound effects can be included in your game for no
  111. additional licensing fees or royalties.  These are not public domain
  112. or shareware sound effects, but professional files.
  113.  
  114. Q: OK, I'm convinced.  How do I order?
  115.  
  116. I thought you might ask that. <g>  From the United States or Canada,
  117. call our 24-hour order hotline at 800-968-9684.  Have your Master
  118. Card or Visa ready, and ask for DiamondWare's Sound ToolKit.  If you
  119. prefer to email an order, send email to Dave Snyder on Compuserve at
  120. 74777,1116.  We'll need your name and address and credit card number
  121. and expiration date to fill your order.  And please, the 800 number
  122. is an order line only.  The folks who take your order barely know
  123. how to use a computer, let alone answer technical questions.  If you
  124. want support or have questions, call 616-245-8376.
  125.  
  126. Alternatively, print out the ORDER.FRM file included with this
  127. demo version, fill it out, and mail it with a check to MVP Software,
  128. 1035 Dallas SE, Grand Rapids, MI 49507-1407.  Or fax it (don't forget
  129. your credit card info) to 616-245-3204.
  130.  
  131. Q: What upgrades are you planning?
  132.  
  133. We're hard at work on protected-mode right now.  By the time you read
  134. this, it may be available.  Beyond that, we're planning on supporting
  135. General MIDI, and other major enhancements.  Contact us for up to
  136. date information.
  137.  
  138. Overseas orders and support, call 616-245-8376.
  139.  
  140. Legal Stuff and credits (boring, but important -- please read it)
  141. -----------------------------------------------------------------
  142. DiamondWare's Sound ToolKit (STK) was designed and developed by
  143. DiamondWare, Ltd. and is marketed and distributed exclusively by
  144. MVP Software, Inc.
  145.  
  146. This software and documentation are Copyright 1994 DiamondWare, Ltd.
  147. All rights reserved.  DiamondWare's Sound ToolKit, DiamondWare's
  148. STK, The STK, DiamondWare, and DW are trademarks of DiamondWare,
  149. Ltd.
  150.  
  151. DiamondWare can be contacted via:
  152.    FAX/BBS: (914) 638-6942
  153.    email:   keith@dw.com
  154.  
  155. MVP can be contacted via:
  156.    FAX:   (616) 245-3204
  157.    email: 74777.1116@compuserve.com
  158.  
  159. DiamondWare's Sound ToolKit was designed and developed by Keith
  160. Weiner and Eric Lorenzen.
  161.  
  162. Example source code was developed by Erik Lorenzen and Keith Weiner,
  163. with language-specific help from David Johndrow (Pascal), and Don
  164. Lemons (BASIC).
  165.  
  166. This document was written by Keith Weiner, with major revisions by
  167. Eric Lund, and a chapter on music/sound development by David
  168. Schultz.  David is a professional musician and has produced music
  169. for several published games.  You can contact David via CompuServe:
  170. 72143,3624.
  171.  
  172. Included sample MIDI song is Copyright 1994 David Schultz, All
  173. Rights Reserved.  Used by permission.  May not be used without
  174. written permission from David Schultz.
  175.  
  176. Proofreading was done by Joyce Peterson, David Ziegler, and Erik
  177. Lorenzen.
  178.  
  179. Miscellaneous utility programs which made the STK possible were
  180. written by David Ziegler.
  181.  
  182. The included FM instrument patch file is courtesy of Rob Wallace of
  183. Wallace Music and Sound.  Rob is a professional musician and has
  184. produced music and sound for many published games.  You can contact
  185. Rob via CompuServe: 71042,1410.
  186.  
  187. Special thanks to Steve Blackwood, John Davis, Steve Estvanik, David
  188. Johndrow, Don Lemons, and David Schultz for testing.
  189.  
  190. 386MAX is a trademark of Qualitas Inc.
  191. Advanced Gravis and Ultrasound are trademarks of Advanced Gravis Computer 
  192. Technology Ltd.
  193. AMD is a trademark of Advanced Micro Devices Corporation
  194. Aria is a trademark of Prometheus Products Inc.
  195. Bane is a trademark of Superego Software
  196. Borland and Turbo Pascal are trademarks of Borland International Inc.
  197. Cyrix is a trademark of Cyrix Corporation
  198. IBM and OS/2 are trademarks of International Business Machines Corporation
  199. Intel is a trademark of Intel Corporation
  200. Microsoft, MS-DOS, and Windows are trademarks of Microsoft Corporation
  201. Novell DOS and Novell are trademarks of Novell Inc.
  202. OPL-2 and OPL-3 are trademarks of Yamaha Corporation
  203. QEMM is a trademark of Quarterdeck Office Systems Inc.
  204. Sound Blaster is a trademark of Creative Labs Inc.
  205. TI is a trademark of Texas Instruments Inc.
  206.  
  207.                          LICENSE AGREEMENT
  208.  
  209. This LICENSE AGREEMENT describes the only terms by which we, MVP
  210. Software, of 1035 Dallas SE, Grand Rapids, MI 49507-1407 permit
  211. distribution of this program.
  212.  
  213. Permission is granted to:
  214. ------------------------
  215. Use it for a 30 day trial period, after which you are required to
  216. register with MVP Software by purchasing Diamondware's Sound
  217. ToolKit.  Under no conditions may you redistribute any or all of the
  218. STK without written authorization from MVP Software, except under
  219. the terms below.  This version of the STK may not be distributed as
  220. part of another software product.
  221.  
  222. Non-commercial Distribution
  223. ---------------------------
  224. Distribution is non-commercial if it is for free, or by any
  225. not-for-profit organization, or by hobby, user or computer interest
  226. group to its members, or by any BBS.  Non-commercial distribution is
  227. permitted without further authorization provided the program is NOT
  228. represented as free or public domain.
  229.  
  230. CD-ROM Distribution
  231. -------------------
  232. If you want to distribute this program on a CD-ROM, YOU MUST OBTAIN
  233. WRITTEN PERMISSION FROM MVP SOFTWARE BEFORE DOING SO.
  234.  
  235. Distribution in a Retail Environment
  236. ------------------------------------
  237. If you want to distribute this program in a retail environment, YOU
  238. MUST OBTAIN WRITTEN PERMISSION FROM MVP SOFTWARE BEFORE DOING SO.
  239.  
  240. TERMS OF PERMITTED COMMERCIAL DISTRIBUTION:
  241.  
  242. By "commercially distribute" we mean to distribute for gain,
  243. including by direct mail, catalog, trade show, or flea market.
  244. Distribution by these means is permitted under the terms below.  For
  245. any other form of distribution, YOU MUST CONTACT MVP SOFTWARE FOR
  246. AUTHORIZATION.
  247.  
  248. By "Program" we mean this version and its related files including
  249. this LICENSE.DOC, distributed by us under the Trademark
  250. "DIAMONDWARE'S SOUND TOOLKIT", and as it may be upgraded or
  251. otherwise modified from time to time.
  252.  
  253. A.  OWNERSHIP: Except to the extent expressly licensed by us, we
  254. have and reserve the exclusive copyright and other right, title and
  255. interest to copy and distribute the Program, and the right to use
  256. the Trademark "DIAMONDWARE'S SOUND TOOLKIT" in connection with it.
  257.  
  258. B.  LICENSE: You are licensed commercially to distribute this
  259. program so long as you [1] market it as shareware using "try before
  260. you buy" or similar words, [2] try to sell only the most current
  261. version of it, [3] make distribution copies only from master copies
  262. received from us using high quality disks and duplication
  263. technology, [4] include the words "MVP Software" in every
  264. description of the program that you put in any catalog or other
  265.  
  266. product promotion, and [5] distribute all of its files together in
  267. compressed or other format as released by us, except that you may
  268. add simple introductory or batch files so long as they do not
  269. interfere with or degrade the performance of the program or any
  270. installation file it may contain.
  271.  
  272. C.  THINGS YOU GET: We will provide to you on request [1]
  273. descriptions of the Program's important features which you may
  274. include in catalogs or elsewhere, [2] descriptions of its hardware
  275. prerequisites.  See "VENDOR.DOC" for details.
  276.  
  277. D.  SOME THINGS YOU DON'T GET: Your right to distribute under this
  278. license is personal, and does not include any right to [1]
  279. sublicense or otherwise cause or permit others to copy or distribute
  280. the program without our consent in writing, or [2] distribute it as
  281. part of any hardware or software package.
  282.  
  283. E.  THE PROGRAM IS PROVIDED "AS-IS".  NO WARRANTIES OF ANY KIND,
  284. EXPRESS OR IMPLIED, ARE MADE AS TO IT OR ANY MEDIUM IT MAY BE ON.
  285. WE WILL PROVIDE NO REMEDY FOR INDIRECT, CONSEQUENTIAL, PUNITIVE OR
  286. INCIDENTAL DAMAGES ARISING FROM IT, INCLUDING SUCH FROM NEGLIGENCE,
  287. STRICT LIABILITY, OR BREACH OF WARRANTY OR CONTRACT, EVEN AFTER
  288. NOTICE OF THE POSSIBILITY OF SUCH DAMAGES.
  289.  
  290. H. MISCELLANY
  291.  
  292. 1.  Since we would be irreparably damaged if Sections A. or B. of
  293. this License were breached, we will be entitled without bond, other
  294. security or proof of damages, to appropriate equitable remedies with
  295. respect to such breaches, in addition to such other remedies as we
  296. may have.
  297.  
  298. 2.  You will hold us, our partners, contractors, employees and
  299. agents harmless from damage, loss and expense arising directly or
  300. indirectly from your acts and omissions in copying, distributing or
  301. adding introductory or installation files to the program.
  302.  
  303. 3.  With respect to every matter arising under this License, you
  304. consent to the exclusive jurisdiction and venue of the state and
  305. federal courts sitting in Grand Rapids, Michigan.
  306.  
  307.                  MVP is Now on CompuServe!
  308.  
  309. You can get all of the latest MVP shareware releases, and discuss
  310. MVP titles directly with the authors on MVP's new section on the
  311. world's largest online information network, CompuServe.  Just type
  312. GO MVPSOFT to get to our section!  If you are not a CompuServe
  313. member you are eligible to receive a FREE trial membership,
  314. including software and online time worth almost $55!  That's right,
  315. you get the CompuServe Information Manager software for DOS or
  316. Windows, which normally costs $29.95.  Plus you get a free first
  317. month of online access, worth $9.95.  And to top it off, you get a
  318. usage credit of $15 of additional online time.
  319.  
  320. To take advantage of this free trial membership to the largest
  321. online service in the world, call 800-848-8199.  Ask for rep 671.
  322. And then GO MVPSOFT and talk to the MVP team on CompuServe.
  323.  
  324.                MVP is Now on Delphi Internet!
  325.  
  326. You can get all of the latest MVP shareware releases, and discuss
  327. MVP titles directly with the MVP team on MVP's new Custom Forum on
  328. Delphi Internet.  Just type GO CUSTOM 45 to get to our section!  If
  329. you are not a Delphi Internet member you are eligible to receive a
  330. FREE trial membership, including 5 free hours of online time plus a
  331. free download of InterNav, Delphi's Windows communication software!
  332.  
  333. To take advantage of this free trial membership to Delphi Internet,
  334. follow these instructions:
  335.  
  336.   1.  Dial by modem, 1-800-695-4002
  337.   2.  Press "Return" once or twice
  338.   3.  At the Username prompt, enter JOINDELPHI
  339.   4.  At the Password prompt, enter CUSTOM45
  340.  
  341. Then GO CUSTOM 45 and talk to the MVP team on Delphi Internet.
  342.  
  343.                  MVP is Now on Novalink!
  344.  
  345. You can get all of the latest MVP shareware releases, and discuss
  346. MVP titles directly with the MVP team on MVP's new forum on
  347. NovaLink.  Just type /GO MVPSOFT to get to our section!  If you are
  348. not a NovaLink member you are eligible to receive a FREE trial
  349. membership, including 10 free hours of online time!
  350.  
  351. NovaLink Interactive Network is one of the top 10 US online services
  352. and the first to offer complete multimedia access to the Internet.
  353. NovaLink provides a full slate of online content and discussion
  354. areas, as well as content and links to information and entertainment
  355. on the Internet, all for less than $10 per month.  NovaLink is
  356. accessed via a local call form more than 1,000 US cities and 100
  357. countries.
  358.  
  359. To take advantage of the free trial offer, including 10 free hours
  360. of online time, call 800-274-2814, Web browse to www.novalink.com,
  361. or email info@novalink.com.  Ask for the "MVP Offer" when you call.
  362.  
  363.        MVP is Now on the Internet and the World Wide Web!
  364.  
  365. You can get all of the latest MVP shareware releases, find out news
  366. of future activities, and give feedback to MVP on the Internet.  To
  367. visit our home page, just set your WWW browser to this URL:
  368.  
  369.    http://theyellowpages.com/shareware/mvp.htm
  370.  
  371. While there, you can see descriptions of all our releases, download
  372. the shareware versions with a click of your mouse button, and check
  373. out full color screen shots for all of our games.  Be sure to leave
  374. feedback telling us how you like our page!  
  375.  
  376. If you prefer using direct ftp to get our files, you can find them
  377. at the following sites:
  378.  
  379.    ftp.uwp.edu/pub/msdos/games/mvp
  380.    ftp.uml.edu/msdos/games/mvp
  381.    wuarchive.wustl.edu/systems/msdos/msdos-games/mvp
  382.  
  383. These sites also have many mirrors, so just look for a game site
  384. with an MVP directory, and you'll be assured of getting the best
  385. games around!
  386.  
  387. By the way, Harold Gregg & Company graciously donated their time and
  388. resources to set up our WWW page, and we highly recommend them to
  389. anyone interested in setting up a home page.  They can be reached at
  390. http://theyellowpages.com.
  391.  
  392.                       All About the STK 
  393.  
  394. What Is It?  What Does It Do?
  395. -----------------------------
  396. DiamondWare's Sound ToolKit (STK) is a sound library written in 99%
  397. real-mode assembler (except for API "wrapper" functions).  It
  398. supports FM music synthesis and digital audio on Sound Blaster and
  399. compatible hardware.
  400.  
  401. The STK can play up to sixteen digital effects at the same time
  402. (called polyphony).  Unlike other sound libraries, there are no
  403. restrictions on calling INT 21h (DOS) functions.
  404.  
  405. It's linkable with any C/C++, Pascal, BASIC, or ASM program, which means
  406. adding the STK to a mostly-completed program will be easy.
  407.  
  408. The STK is built tough.  DiamondWare has acquired over thirty sound
  409. boards, fifty books (including manufacturer's specifications), four
  410. operating systems, and five brands of CPUs to test the STK during
  411. development.  All this testing means that programmers who use the
  412. STK won't field millions of tech-support calls saying "the sound
  413. doesn't work," or "it doesn't crash unless I enable the sound
  414. option."
  415.  
  416. The STK's autodetect is powerful.  It can determine the hardware
  417. type, port, DMA channel, and IRQ level automatically--under every
  418. major DOS environment (including Windows DOS boxes, OS/2 DOS boxes,
  419. Novell DOS, QEMM, 386MAX, and EMM386), running on every major brand
  420. of CPU, including Intel, AMD, Cyrix, IBM, and Texas Instruments.
  421. The STK goes directly to the sound hardware, requiring neither
  422. environment variables nor user input.  And, should you wish, you can
  423. override any setting.
  424.  
  425. The STK provides "mixer" functionality.  The better boards (Sound
  426. Blaster Pro and up) have chips on-board which can control the volume
  427. level of music and sound effects independently, and also the total
  428. volume.  For sound boards that don't have such a chip, the STK can
  429. mix levels in software.
  430.  
  431. DiamondWare's STK supports an important subset of the MIDI
  432. specification, including true dynamic patch changes, velocity
  433. sensitivity, pitch bend, and aftertouch.  Future versions of the STK
  434. will support more of the MIDI specification.
  435.  
  436. The STK doesn't allocate any memory dynamically.  It doesn't make
  437. any INT 21h calls (except during autodetect and initialization).  It
  438. doesn't require any outside code to link.  It doesn't have to
  439. reprogram the timer hardware, though it comes with optional code to
  440. do this.  The STK doesn't take hundreds of kilobytes of RAM.  It
  441. doesn't pollute your users' install directories with scores of
  442. files.  And it doesn't use a single line of code from a sound board
  443. manufacturer, or any other library vendor.
  444.  
  445. What Are Its Limitations?
  446. -------------------------
  447. The STK is a kit for Sound Blasters, SB-compatibles, and SB-clones.
  448. It will not work with the native modes of non-Creative Labs' sound
  449.  
  450. boards.  [Creative Labs is the major player in the sound board
  451. market.]  However, it has been designed and tested to work with their
  452. compatible modes, (which are often only 90-95% "compatible").
  453.  
  454. It requires a 386SX or higher processor .  This is not because it
  455. uses so much computing power (it doesn't), but because we've made
  456. extensive use of instructions and registers which are unavailable on
  457. the 286 and lower.
  458.  
  459. The STK can't play VOC files (sound effects) greater than 64k,
  460. although it supports easy sequencing of split-up VOC files.
  461.  
  462. The STK needs interrupts to remain active.  Disabling interrupts for
  463. extended periods of time will pause all sound playback, until
  464. interrupts are enabled again.  Music notes will hang, and digitized
  465. will skip and repeat like a CD player trying to track a bad disc.
  466.  
  467. The STK does not support sampling rates under 4 KHz or over 24 KHz.
  468.  
  469. The STK does not manage resource files, nor play files from disk.
  470. You must manage your directory structure, and load each file into a
  471. buffer before the STK can play it.
  472.  
  473. The STK can't change its settings (like volume levels) "in the
  474. background".  If you want to do this, then write some code that
  475. checks the current time, and slowly change the volume level.  It's
  476. no harder than moving 20 space aliens, a player, and 5 bullets.
  477.  
  478.                        Before You Start
  479.  
  480. Prerequisite Knowledge
  481. ----------------------
  482. DiamondWare's STK is a programmer's library, not a game.  As such,
  483. it's a highly technical product.  While this document was written to
  484. tell you all about the STK, it can't tell you how to program.
  485. Before reading this document, you should be familiar with PC
  486. programming -- including bitwise operations and linking with external
  487. libraries.
  488.  
  489. The STK was designed to work with C/C++, Pascal, and BASIC.  Even if
  490. you will not be programming in C, several conventions and examples
  491. in this manual are given only in C, so prior C experience will be
  492. helpful.  For example, all function prototypes are given for C,
  493. Pascal, and BASIC; but in general, descriptions are given only using
  494. C terminology.  Here is a guide for Pascal and BASIC users to aid in
  495. understanding C:
  496.  
  497. All subroutines are called "functions", although in Pascal and BASIC
  498. they may be "functions", "procedures", or "subroutines".  A C
  499. struct, often called a structure, is the equivalent of a Pascal
  500. record and a BASIC TYPE.
  501.  
  502. C expresses bitwise OR as a pipe |, bitwise AND as an ampersand &,
  503. logical OR as two pipes ||, and logical AND as two ampersands &&.  C
  504. comments are either a double slash //Comment which is a comment
  505.  
  506. until the end of the line (equivalent to BASIC's apostrophe or REM)
  507. or /*Comment*/ (equivalent to Pascal's (*Comment*)).  BASIC
  508. programmers should ignore all underscores _.
  509.  
  510. There's one other important thing for Pascal and BASIC programmers
  511. to know about C.  The ampersand & operator can also be used to take
  512. the address of a variable.  For example:
  513.  
  514.                 dws_MSongStatus(&mstat);
  515.  
  516. This call passes the address of the variable mstat to the function
  517. (which puts the song's status into the variable).  This is
  518. equivalent to Pascal's var or BASIC's SEG (pass by reference)
  519. calling conventions.
  520.  
  521. In specific instances, Pascal and BASIC differences with C will be
  522. explicitly listed.
  523.  
  524. Sometimes in this document, Turbo Pascal is distinguished from other
  525. languages.  This is because Pascal works with "units."  A unit
  526. contains not only the linkable program code, but also the
  527. declarations which tell the compiler about that program code and the
  528. data types it requires.  C and BASIC use a different model, in which
  529. the compiler is told to include some human-readable header file,
  530. which contains declarations of code and data types, but no more.
  531. The compiler produces a .OBJ file, which the linker puts together
  532. with other .OBJ files (and .LIB files, which are really just several
  533. .OBJ files in one) to make the final .EXE.
  534.  
  535. The Sound ToolKit is distributed with a single .LIB which works with
  536. all Microsoft languages, Borland C/C++, and Turbo Assembler.  Header
  537. files are provided for C/C++ and BASIC.  Also included are unit
  538. files for Turbo Pascal versions 6 and 7.
  539.  
  540. All source files provided on disk were produced with tabs set to 2.
  541.  
  542.                        Installing the STK
  543.  
  544. The STK is distributed on a single disk containing two files:
  545. INSTALL.COM and STK.EXE.  To install the STK simply insert the
  546. distribution disk into drive A or B, and type A: or B:, and press
  547. ENTER.  Then type INSTALL, and press ENTER.  The installation
  548. program will create a directory and install the files to it.
  549.  
  550. If you have downloaded it, simply unzip the zip file (using Pkunzip
  551. 2.04 or higher) into a directory on your hard drive.
  552.  
  553. Either way, that's it; it's installed.
  554.  
  555. Make sure you put the header files and the library file (or the
  556. Pascal unit file) where the compiler and linker can find them.  If
  557. you need more information on this and related topics, your
  558. compiler's manual will be far more detailed than is possible here,
  559. and will cover your specific software environment.
  560.  
  561. You may want to put the executables (MID2DWM.EXE, VOC2DWD.EXE, etc.)
  562. in an existing binaries directory, or set the PATH environment
  563.  
  564. variable to point to them.  Your MS-DOS manual describes this in
  565. detail.
  566.  
  567.                     Linking With the STK
  568.  
  569. The STK has been designed so that calling it in a real-world program
  570. is relatively simple.  However, the STK is a non-trivial component
  571. of your program, and there are some non-obvious things to know.
  572.  
  573. As mentioned above, the STK works with C/C++, Pascal, and BASIC.
  574. Additionally, it should work with any other linkable language which
  575. supports the Intel/Microsoft .OBJ file format specification (such as
  576. assembler).  If you are using such a language, you will have to port
  577. the C header files to your language.  Link with DWS.LIB as you would
  578. with any other library.
  579.  
  580. By far, the easiest way to use the STK is in large model programs.
  581. In a large model program, all function calls and all data references
  582. are made via 32-bit segment:offset addresses.  The STK expects this
  583. convention.
  584.  
  585. It's possible to use the STK in mixed model programs, where some
  586. code or data is "near" and other code or data is "far."  As long as
  587. the STK's code and data is all "far," this can work.  See your
  588. compiler manual for details on how to do this.
  589.  
  590.                     About Music and Sound
  591.  
  592. Introduction
  593. ------------
  594. Sound, especially in the PC world, is a complicated topic.  This
  595. section will serve as an overview of the subject.  The STK provides
  596. functionality for the two primary aspects of sound programming: FM
  597. synthesis for playback of MIDI (.MID format) music, and digital
  598. audio for playback of digitally sampled (.VOC format) sound effects.
  599.  
  600. FM Synthesis
  601. ------------
  602. FM stands for "Frequency Modulation," which refers to how musical
  603. notes are created.  In FM, a sound is created from two operators,
  604. which are simple sine waves.  One operator, called the modulator, is
  605. used to modify the frequency output by the other, called the
  606. carrier.  The resulting waveform is surprisingly rich (much more so
  607. than Amplitude Modulation).  FM synthesis is a convenient method for
  608. playing music.
  609.  
  610. The waveform is put through an envelope, which alters the output
  611. volume during the four distinct phases of a musical note: attack,
  612. sustain, release, and decay.
  613.  
  614. On Sound Blasters, FM synthesis is performed by a Yamaha OPL-2 or
  615. OPL-3 chip in the digital domain.  The total output of all voices is
  616. sent to a special Yamaha Digital-to-Analog Converter (DAC), which
  617. creates low-level analog signals.
  618.  
  619. Programmed properly, the FM synthesizer can produce fairly nice
  620. instrument sounds, including surprisingly good drums.  The key
  621.  
  622. phrase here is "fairly nice." If you want to create a mood, you can
  623. do it with FM synthesis.  However, you cannot realistically
  624. reproduce the sound of most acoustic instruments (FM does a better
  625. job with "electronic" sounds).
  626.  
  627. Music is created by a musician, a computer, and sequencer software.
  628. Usually he'll use a (music) keyboard controller to enter note data,
  629. although some musicians may type it in on their computer's keyboard.
  630.  
  631. The result of the musician's toil and effort, the .MID file, is a
  632. collection of note information, but it isn't sufficient to make
  633. music; it contains no information about what the instruments should
  634. sound like.  A patch bank, which is a set of instrument definitions,
  635. fills this gap.  This nomenclature comes from the old days when
  636. technicians plugged patch cords into racks of equipment to change
  637. synthesizer sounds.  Today, patch is a synonym for a single musical
  638. instrument sound.
  639.  
  640. The OPL FM chip uses eleven parameters to describe an instrument.  A
  641. single instrument patch is therefore 11 bytes (plus a header and
  642. some waste).  Software such as Symphonix OPL Patch Editor/Librarian
  643. by Flashpoint Productions (included with the registered version of
  644. the STK) is the best way to tinker with patches.
  645.  
  646. Collections of patches are stored in instrument bank files (.IBK
  647. format).  Although you can put any instrument at any index in the
  648. file, you're going to discover that only songs custom-written for
  649. that instrument bank file will play correctly.  Other songs will
  650. probably sound totally unacceptable.
  651.  
  652. Enter the General MIDI standard, which specifies all 128 patches
  653. (e.g. instrument 1 is Grand Piano).  Although, for FM synthesis,
  654. General MIDI compliance is not required, we strongly recommend it.
  655. When the industry moves to wavetable boards, your music will sound
  656. good on most boards.  (Eventually, all sound hardware will support
  657. General MIDI and wavetable.  But today's installed base is about 99%
  658. FM and 1% wavetable.  Sales of FM hardware are still much higher
  659. than wavetable.  Wavetable sales are projected to surpass FM sales
  660. in 1996.  Wavetable installations will surpass FM no earlier than
  661. 1997.  Considering this, and the fact that many wavetable boards
  662. also include or emulate FM, we believe FM is far more important than
  663. wavetable right now.  Good FM is currently a big market advantage.)
  664.  
  665. Potential Music Problems
  666. ------------------------
  667. The STK music playback engine may behave differently than you'd expect.
  668. The following is a brief discussion of two bona fide features which may
  669. cause some unexpected problems.
  670.  
  671. The STK is extremely sensitive to velocity.  If you play a song and the
  672. drums or an instrument sound faint (or loud), this is why.  Change the
  673. output level of the instrument patch, or use your sequencer to bring up
  674. the volume of the problem track.
  675.  
  676. The STK will allow notes of bells and strings to "ring out" after they are
  677. "key released".  If this is causing undesired effects, simply make your
  678. instrument patches "sustaining".  The STK will shut such notes down
  679. immediately when they are released.
  680.  
  681. Digital Audio
  682. -------------
  683. In digital audio, an analog waveform is translated into the digital
  684. domain by sampling (i.e. measuring) the amplitude of the wave at
  685. regular intervals.  The sampling rate is the frequency at which this
  686. is done.
  687.  
  688. As Nyquist proved, the sampling rate must be at least twice as high
  689. as the highest frequency in the waveform being sampled, or else
  690. aliasing occurs.  When this happens, the sound takes on an
  691. unpleasant metallic overtone.
  692.  
  693. Let's say you're recording the sound of glass breaking, which
  694. includes some very high frequencies -- we'll assume up to about 11
  695. KHz.  Unless you're using a low-pass analog filter (the Sound
  696. Blasters have several) to cut out high frequencies, you should
  697. sample at 22 KHz or higher.
  698.  
  699. Note: sampling at very low rates will have undesirable side-effects.
  700. Speech will be lisped, and in general, everything will sound dull.
  701.  
  702. Dynamic range, which is the difference between the softest and
  703. loudest sounds, is also important.  16-bit samples sound better than
  704. 8-bit samples because the extra byte allows more precision, and more
  705. contrast between soft and loud.
  706.  
  707. It is important to record your sound effects at a low volume, if you
  708. plan on playing more than one or two simultaneously.  You can also
  709. compress the dynamic range when you prepare the sound.  This will
  710. help you avoid clipping (i.e. exceeding the dynamic range of the
  711. playback hardware).
  712.  
  713.                        General Guidelines
  714.  
  715. Don't Touch That Compiler Yet!
  716. ------------------------------
  717. Before you can bring sound into your program, you must convert the
  718. .MID and .VOC files into formats that are quickly and easily parsed
  719. at run-time.  Use MID2DWM and VOC2DWD, respectively.  See the
  720. Utilities heading in the Reference section for more information on
  721. how to use these programs.
  722.  
  723. The Autodetect
  724. --------------
  725. Before you can initialize the STK, you must know the sound hardware
  726. settings: base port, DMA channel, and IRQ level.  The STK provides an
  727. autodetect routine to determine these.
  728.  
  729. Using the autodetect is easy.  Create two structs, one of type
  730. dws_DETECTOVERRIDES, and the other of type dws_DETECTRESULTS.  Set
  731. the baseport, digdma, and digirq fields of the overrides struct to
  732. 65535 (to autodetect them), or initialize them with their correct
  733. values.  Either way, call dws_DetectHardWare, passing the address of
  734. both structs as parameters.  The results struct will be filled in.
  735.  
  736. Note: you must call dws_DetectHardWare even if you know these values
  737. in advance.  The reason is that it stores information in the
  738. reserved field of the dws_DETECTRESULTS struct.
  739.  
  740. Note: If you write the settings to a disk file, make sure you write
  741. the entire struct.  dws_Init requires the information in the reserved
  742. field and may crash if it's not there.
  743.  
  744. For more information about these and other structures, see Data
  745. Structures in the Reference section.
  746.  
  747. Many sound boards require the user to load drivers from either
  748. CONFIG.SYS or AUTOEXEC.BAT (e.g. the Advanced Gravis Ultrasound and
  749. SBOS) These drivers must be loaded before any STK-enabled software
  750.  
  751. is run.  If their drivers aren't loaded, some boards may not respond,
  752. or worse yet, could take on default values which conflict with other
  753. hardware.  This last case is a major potential problem and could
  754. cause a crash.
  755.  
  756. In the overwhelming majority of cases, the autodetect will quietly
  757. do its job.  It is robust, and there are only two known (obscure)
  758. failure cases.  If you find any others, please report them to
  759. DiamondWare!
  760.  
  761. The first failure case occurs only when the STK is running in a
  762. Microsoft Windows Enhanced-mode DOS box.  If the user has another
  763. card which is constantly doing DMA on an 8-bit channel, the STK will
  764. crash the machine.  The only card known to do this is the NE2100 bus
  765. mastering ethernet adapter, which uses a 16-bit DMA channel 99% of
  766. the time.  (It's an expensive, high-performance card; running it on
  767. an 8-bit DMA channel is like putting 85-octane gas into a sports
  768. car.)  Other devices that use DMA, like CD-ROM and SCSI controllers,
  769. do not perform DMA transfers unless they are in use, and will not
  770. cause any problems with the STK.
  771.  
  772. The second failure case occurs only with Aria 16 and Aria 16se
  773. cards.  If the Sound Blaster portion of the board is configured for
  774. IRQ 2/9, the autodetect will incorrectly return the IRQ used by the
  775. MIDI portion of the board, rather than that of the digitized
  776. portion.
  777.  
  778. Initializing the STK
  779. --------------------
  780. After calling dws_DetectHardWare, you'll need a struct of type
  781. dws_IDEAL.  Its fields are requests for STK services.  Set each to
  782. the desired values.  Then call dws_Init, passing the address of the
  783. dws_DETECTRESULTS and dws_IDEAL structs as parameters.
  784.  
  785. This struct is here for three reasons.  The first is to tell the STK
  786. the initial sampling rate you want.  The second reason is to
  787. conserve CPU cycles.  The STK will run faster with fewer digital
  788. voices.  The last reason is that future versions of the STK will
  789. offer more features (e.g. 16-bit, stereo, etc.)  You may not want
  790. some or all of these services.  Initialize this struct properly, and
  791. you will easily incorporate STK upgrades into your programs.
  792.  
  793. When the STK initializes, it resets the sound hardware to a 100%
  794. known state, including setting the mixer to maximum volume.  It also
  795. sets up its own internal data structures, Interrupt Service Routines
  796. (ISRs), etc.  Few STK functions will work until you call dws_Init.
  797.  
  798. The Hardware Timer
  799. ------------------
  800. Next, initialize the hardware timer.  The STK must be called at a
  801. relatively high rate.  The DiamondWare Timer (DWT) module will do
  802. the trick, or you can use your own code.
  803.  
  804. If you're going to use the DWT, call dwt_Init, passing it a rate
  805. constant as a parameter.  The DWT will do all timing functions
  806. necessary to the STK (and keep time for your game, too).  See
  807. dwt_Init in the Function Reference for complete information.
  808.  
  809. If you have your own code, initialize it now.  Make sure it will
  810. call dws_Update once during each hardware timer interrupt.  The DWT
  811. will not interfere, or even link into your application.
  812.  
  813. Initiating Playback
  814. -------------------
  815. To play a song, first allocate a buffer large enough to hold the
  816. .DWM file, and then read it in.  Create a struct of type dws_MPlay;
  817. set the track field to point to this buffer, and the count field to
  818. the number of times to play.  Now call dws_MPlay.  The song will
  819. play in the background.
  820.  
  821. To play a sound effect, allocate a buffer, and read in the .DWD
  822. file.  Create a struct of type dws_DPlay; set the snd field to point
  823. to the buffer, the count field to the number of times to play,
  824. ignore priority field (for now), and set the presnd field to 0 (for
  825. now).  Now call dws_DPlay.  The sound will play in the background.
  826.  
  827. For more information on these structs and calls, see the Advanced
  828. Tutorial section, or The Functions heading and The Data Structures
  829. heading in the Reference section.
  830.  
  831. Note to BASIC users: make sure that your buffers don't move around
  832. during "garbage collection".
  833.  
  834. The Rules of the Game
  835. ---------------------
  836. The STK can play one music track, and up to sixteen sound effects
  837. (at the same sampling rate) at the same time.  Once a song or sound
  838. is playing, you can let it play without doing anything else.  You
  839. can even make DOS calls.
  840.  
  841. In the mode used by the STK, the FM chip allows up to 6 musical
  842. instruments and 5 drums to play simultaneously.  Drums can play and
  843. replay, still sounding good, but it's important that your music
  844. sound (and/or sustain) no more than 6 melody notes at a time.  The
  845. STK player will automatically drop notes out (though it won't
  846. crash), but a musician would inevitably make a better decision as to
  847. which notes are important than any computer algorithm.
  848.  
  849. There are five drums built in to the STK, chosen as a reasonable
  850. compromise: bass drum, snare, high hat, tom tom, and top cymbal.
  851. All other drums are mapped to these five.
  852.  
  853. The STK will refuse to exceed the dynamic range of the hardware it's
  854. playing on.  This means that if you try to play 4 sound effects
  855. which all use the full 8 bits of dynamic range, you'll only hear the
  856. one with the highest priority.  Until it ends, the others will not
  857. be played, although they will continue to advance silently.  If the
  858. sound with the highest priority ends, any remaining sounds are added
  859. back in, to the limit of the dynamic range of the playback hardware.
  860.  
  861. Playback Status
  862. ---------------
  863. The functions dws_MSongStatus and dws_DSoundStatus determine whether
  864. a song or sound is playing or finished.  Each of these functions
  865. requires you to create a status variable for them to use.  To get
  866.  
  867. the status of your music, pass the address of the status variable to
  868. dws_MSongStatus.  To query the status of a specific sound effect,
  869. pass the address of the status variable, as well as its ID (from the
  870. soundnum field of its dws_DPLAY structure) to dws_DSoundStatus.
  871.  
  872. Each bit of the status variable is a flag.  Perform a bitwise and
  873. between the status variable and the playback condition you would
  874. like to test.  For example, dws_MSONGSTATUSPLAYING & status
  875. evaluates to a 1 if the music is still playing, and
  876. dws_DSOUNDSTATUSPLAYING & status evaluates to a 1 if the sound
  877. effect is still playing.  For a complete list of conditions, refer
  878. to both routines in the The Functions heading in the Reference
  879. section.
  880.  
  881. Keeping Time
  882. ------------
  883. The DWT provides a double-word (32 bit, unsigned) timer, which
  884. begins at 0 when DWT is initialized, and increments once per timer
  885. interrupt.  Calling dwt_MasterTick returns the number of clock ticks
  886. since time began (i.e.  when you called dwt_Init).  dwt_Pause and
  887. dwt_UnPause suspend and restart the master clock, respectively.
  888. They don't affect either music or digitized sound playback.
  889.  
  890. Tracking Errors
  891. ---------------
  892. Most functions in the STK return a word (16-bit, unsigned) value.
  893. This is a boolean value, indicating the success/failure of the
  894. function.  True (1) is success, and false (0) means that an error
  895. has occured.  In the case of an error, call dws_ErrNo to determine
  896. what happened.
  897.  
  898. dws_ErrNo behaves much like the errno variable in the C standard
  899. library.  Initially it's 0, and it's only changed when a function
  900. encounters an error.  It's important to check it after each call
  901. which fails, or else you won't know which one generated the error.
  902. Under The Functions, in the Reference section, there is a list of
  903. errors for each function.  You may assume this list is exhaustive;
  904. if an error isn't listed for a given function, then that function
  905. cannot generate that error.
  906.  
  907. Stopping Playback
  908. -----------------
  909. Call dws_MPause or dws_MUnPause to suspend or restart music
  910. playback.  Call dws_MClear to stop the current song.  Make sure you
  911. stop music playback before you deallocate the song buffer.
  912.  
  913. Call dws_DPause or dws_DUnPause to suspend or restart all digitized
  914. sound playback.  Call dws_DClear to stop all currently-playing
  915. sounds.  Call dws_DDiscard to stop a particular sound from playing;
  916. this function requires the sound's ID as a parameter (from the
  917. soundnum field of its dws_DPLAY structure).  Call dws_DDiscardAO to
  918. stop all occurrences of a digitized sound; this function requires a
  919. pointer to the sound's buffer.
  920.  
  921. Shutting Down
  922. -------------
  923. Before exiting to DOS, you must clean up.  First, call dwt_Kill (or
  924. shut down your own timer module).  Next, call dws_Kill.  Finally,
  925. deallocate any buffers you may have allocated during execution.
  926.  
  927. There is a problem in Microsoft Windows Enhanced-mode DOS boxes when
  928. the sound board is set to IRQ 2/9, and Windows isn't configured for
  929. the sound board.  The first time an STK-using program runs in this
  930. environment, it will work perfectly.  But if the user exits the
  931. STK-using program, and restarts it before restarting Windows, there
  932. will be no digitized sound (FM music will play normally).
  933.  
  934. Re-entrancy
  935. -----------
  936. The STK is re-entrant.    You can call its functions from your ISR's
  937. (interrupt service routines).  Just make sure you heed the dws_BUSY
  938. error.    If this occurs, make the call again later.
  939.  
  940.                           Tutorial 
  941.  
  942. This tutorial will walk you through MINAPP.C, an application
  943. framework which fulfills the minimum requirements for implementing
  944. the STK in a program.  It is intended for learning the basics; it
  945. does not check for STK errors at all.  The source code for the
  946. sample applications PLAYDWD, PLAYDWM, and FINDSB are provided in C,
  947. Pascal, and BASIC on disk.  They include (more) robust
  948. error-checking, and are highly commented.  Please review them also.
  949.  
  950. Setting Up:  Includes and Variables
  951. -----------------------------------
  952. #include <stdio.h>
  953. #include <malloc.h>
  954. #include "dws.h"
  955. #include "dwt.h"
  956.  
  957. void main (void)
  958. {
  959.     FILE *fp;
  960.     byte __far *sound, *song;
  961.     word mstatus, dstatus, msize, dsize;
  962.     dws_DETECTOVERRIDES dov;
  963.     dws_DETECTRESULTS   dres;
  964.     dws_IDEAL ideal;
  965.     dws_MPLAY mplay;
  966.     dws_DPLAY dplay;
  967.  
  968. The standard C header file stdio.h is included for the file I/O
  969. functions, and malloc.h to support dynamic memory allocation.  dws.h
  970. contains all the STK prototypes, #defines, structures, and type
  971. definitions.  dwt.h provides the same, for the DWT.
  972.  
  973. MINAPP loads one sound effect, and one piece of music.  sound, a
  974. pointer, holds the address of the sound effect buffer; song, another
  975. pointer, holds the address of the music buffer.  dplay, a struct,
  976. holds all information needed to play the sound effect; mplay,
  977. another struct, holds information for playing the song.  dov, dres,
  978. and ideal are structs required for initialization.
  979.  
  980. Loading Songs and Sounds
  981. ------------------------
  982. /* ALLOCATE MEMORY FOR SOUND FILE AND LOAD IT */
  983.     fp = fopen("minapp.dwd", "rb");
  984.     fseek (fp, 0L, SEEK_END);
  985.     sound = _fmalloc (dsize=ftell (fp));
  986.     fseek (fp, 0L, SEEK_SET);
  987.     fread (sound, dsize, 1, fp);
  988.     fclose (fp);
  989.  
  990. /* ALLOCATE MEMORY FOR SONG FILE AND LOAD IT */
  991.     fp = fopen("minapp.dwm", "rb");
  992.     fseek (fp, 0L, SEEK_END);
  993.     song = _fmalloc (msize=ftell (fp));
  994.     fseek (fp, 0L, SEEK_SET);
  995.     fread (song, msize, 1, fp);
  996.     fclose (fp);
  997.  
  998. These two sections allocate buffers to store the music and the
  999. sound, then read the files into them.  minapp.dwm began life as
  1000. minapp.MID and gm.ibk, and was converted by MID2DWM.  minapp.dwd
  1001. began as MINAPP.VOC, and was converted by VOC2DWD.
  1002.  
  1003. Initializing the STK
  1004. --------------------
  1005. /* AUTODETECT SOUND CARD */
  1006.     dov.baseport = 65535;
  1007.     dov.digdma   = 65535;
  1008.     dov.digirq   = 65535;
  1009.     dws_DetectHardWare (&dov, &dres);
  1010.  
  1011. /* INITIALIZE DIAMONDWARE STK SYSTEM */
  1012.     ideal.musictyp   = 1;
  1013.     ideal.digtyp     = 8;
  1014.     ideal.digrate    = 10989;
  1015.     ideal.dignvoices = 16;
  1016.     ideal.dignchan   = 1;
  1017.     dws_Init (&dres, &ideal);
  1018.  
  1019. Notice how all fields in the struct, dov, are set to 65535.  This
  1020. tells dws_DetectHardWare to autodetect the corresponding sound
  1021. hardware parameters.  The results of this are returned in the dres
  1022. struct.  We initialized the ideal struct to request the desired STK
  1023. services (in this case overkill, since we only need one digitized
  1024. voice).  When we call dws_Init, the sound hardware and the STK are
  1025. set up for business.
  1026.  
  1027. Optional Timer Module
  1028. ---------------------
  1029. /* INITIALIZE OPTIONAL TIMER MODULE */
  1030.     dwt_Init (dwt_72_8HZ);
  1031.  
  1032. A PC bootstraps (starts up) with a rate of 18.2 clock ticks per
  1033. second, but the STK requires a higher rate.  Just as importantly,
  1034. the STK must be called during each clock tick.  The DiamondWare
  1035. Timer module will do this.  We recommend 72.8 Hz, a good compromise
  1036. between music quality and Windows DOS-box compatibility.  (If you
  1037.  
  1038. don't care about Windows DOS boxes, use 145.6 Hz.)
  1039.  
  1040. Preparing Songs and Sounds
  1041. --------------------------
  1042. /* PREPARE SONG FOR PLAYING */
  1043.     mplay.track = song;
  1044.     mplay.count = 1;
  1045.  
  1046. /* PREPARE SOUND FOR PLAYING */
  1047.     dplay.snd      = sound;
  1048.     dplay.count    = 1;
  1049.     dplay.priority = 1000;
  1050.     dplay.presnd   = 0;
  1051.     dws_DGetRateFromDWD (dplay.snd, &ideal.digrate);
  1052.     dws_DSetRate (ideal.digrate);
  1053.  
  1054. The mplay struct is set up so that a call to dws_MPlay will play the
  1055. song once.  The dplay struct is also set up.  A priority of 1000 is
  1056. arbitrarily chosen, but since no other sound effects will be playing
  1057. in MINAPP, this field has no practical effect.  The presnd field is
  1058. also unused (set to 0), because this example does not sequence
  1059. digital sounds.  The current playback rate is set to the sampling
  1060. rate at which the sound was recorded.
  1061.  
  1062. Initiating Playback
  1063. -------------------
  1064. /* PLAY SONG AND SOUND ONCE */
  1065.     dws_MPlay (&mplay);
  1066.     dws_DPlay (&dplay);
  1067.  
  1068. A call to dws_MPlay starts the music, and a call to dws_DPlay begins
  1069. playback of the digitized sound effect.
  1070.  
  1071. Wait 'Til the Fat Lady Stops Singing
  1072. ------------------------------------
  1073. /* MAIN LOOP */
  1074.     do
  1075.     {
  1076.         dws_DSoundStatus(dplay.soundnum, &dstatus);
  1077.         dws_MSongStatus(&mstatus);
  1078.     }
  1079.     while ((mstatus & dws_MSONGSTATUSPLAYING) ||
  1080.        (dstatus & dws_DSOUNDSTATUSPLAYING));
  1081.  
  1082. We query the song and sound status.  The status is placed in a
  1083. bitfield variable, via its address.  In the case of the music, we're
  1084. interested in the dws_MSONGSTATUSPLAYING field; in the case of the
  1085. digitized sound effect, we're interested in the
  1086. dws_DSOUNDSTATUSPLAYING.  When this field is 1, it means that the
  1087. song or sound, respectively, is playing.
  1088.  
  1089. Shutting Down
  1090. -------------
  1091. /* CLEAR ALL ALLOCATED MEMORY */
  1092.     _ffree (song);
  1093.     _ffree (sound);
  1094.  
  1095. /* DE-INITIALIZE STK */
  1096.     dwt_Kill();
  1097.     dws_Kill();
  1098. }
  1099.  
  1100. The buffers containing the music and sound effect are now
  1101. deallocated.  Normally, dws_DClear and dws_MClear would be called
  1102. before freeing these buffers, but since we know that no sounds are
  1103. playing at the moment, the calls are unnecessary.  The DWT is
  1104. de-initialized first by calling dwt_Kill, then the entire STK engine
  1105. is shut down by calling dws_Kill.  That's it!
  1106.  
  1107.                         Advanced Tutorial 
  1108.  
  1109. Working with the Advanced Features
  1110. ----------------------------------
  1111. The example code fragments below illustrate sequencing and polyphony. We 
  1112. assume that the STK has been initialized.  sfx1 and sfx2 are digital sounds in
  1113. memory.  The following shows how the two dws_DPLAY structures are set up:
  1114.  
  1115.         dplay1.snd      = sfx1;
  1116.         dplay2.snd      = sfx2;
  1117.         dplay1.count    = 1;
  1118.         dplay2.count    = 1;
  1119.         dplay1.priority = 500;
  1120.         dplay2.priority = 1000;
  1121.         dplay1.presnd   = 0;
  1122.         dplay2.presnd   = 0;
  1123.  
  1124. Each sound effect is set to play once, and the second sound is given
  1125. a higher priority than the first.  The presnd field of both structs
  1126. is not set for sequencing.
  1127.  
  1128. Sequencing
  1129. ----------
  1130. The presnd field allows you to sequence sounds to play one after the
  1131. other.  The first sample of the second sound plays after the last
  1132. sample of the first sound.  The effect is that of a single sound,
  1133. playing seamlessly.
  1134.  
  1135. This feature is useful if you want to break a long sound into
  1136. several pieces which can fit into memory.  Or a sound may have
  1137. several different continuations, depending on player input (e.g.  a
  1138. gun fires, continuing with either a scream or a ricochet, depending
  1139. on whether the bullet hits).
  1140.  
  1141. Set the presnd field of a dplay struct to the soundnum of the sound
  1142. you want to sequence after, or use 0 if the sound is stand-alone.
  1143.  
  1144. Note: if you specify a non-zero sound number (which corresponds to a
  1145. sound actually playing), the value returned in soundnum is the same
  1146. as the value specified in presnd.  The new sound will not play
  1147. immediately, but will wait until the first sound is done.
  1148.  
  1149. The priority field is not related to sequencing.
  1150.  
  1151.     dws_DPlay (&dplay1);
  1152.     dplay2.presnd = dplay1.soundnum;
  1153.     dws_DPlay (&dplay2);
  1154.  
  1155. This plays dplay1 followed by dplay2.  If you are sequencing more
  1156. than two sounds, call dws_DSoundStatus to determine when it's safe
  1157. to sequence each sound after the second.
  1158.  
  1159. Polyphony
  1160. ---------
  1161. To play multiple digital sounds, call dws_DPlay more than once.
  1162.  
  1163. The presnd field has no bearing on polyphony.
  1164.  
  1165.     dws_DPlay (&dplay1);
  1166.     dws_DPlay (&dplay2);
  1167.  
  1168. The sounds start simultaneously.  dplay1, the first sound, has a
  1169. priority of 500.  dplay2 has a priority of 1000.
  1170.  
  1171. These numbers are arbitrary; it is the relationship between them
  1172. that counts.  Priorities of 1 and 2 will have the same results.
  1173.  
  1174. Note: if these two sounds together do not exceed the dynamic range
  1175. of the hardware, they'll both play.  However, if the total dynamic
  1176. range used by both sounds exceeds 8 bits, then you will hear only
  1177. the second sound (its priority is higher).  If the second sound is
  1178. shorter, then the first sound will be heard when the second one
  1179. ends.  Until then, it will advance silently.
  1180.  
  1181. Autodetection and Setup Programs
  1182. --------------------------------
  1183. Finding the user's sound board is non-trivial, because the user often
  1184. doesn't even know what brand he owns, let alone its settings.  So the STK
  1185. asks the hardware directly.
  1186.  
  1187. It does a good job, but there are some potential problems.  Sometimes, the
  1188. STK may be unable to find one or more sound hardware parameters (almost
  1189. always the problem lies with finding the DMA channel).
  1190.  
  1191. The capability field in the dws_DETECTRESULTS struct will tell you if the
  1192. STK found everything it needed for music and for digitized.  If both
  1193. capability flags are set, then you have nothing further to do; music and
  1194. sound will work.
  1195.  
  1196. However, only the dws_capability_FM flag might be set.  This may be because
  1197. the user has music-only hardware, or it may be that (for example) the STK
  1198. was unable to find the DMA channel.  To tell the difference, look at the
  1199. baseport field of the dws_DETECTRESULTS struct.  If this field returns as
  1200. either 65535 or 388h, this means that no digitized-capable sound hardware
  1201. is present (or the user's drivers aren't installed).  If this field returns
  1202. with any other value, it means that digitized hardware exists.  Look at the
  1203. digirq and digdma fields.  If either or both of these are set to 65535, it
  1204. means that the STK couldn't autodetect them (and the BLASTER environment
  1205. variable was either not present, or was wrong).
  1206.  
  1207. Planning ahead for this, you should have a screen where the user can type in
  1208. port, DMA, and IRQ channel.  Don't require him to do this, but make this
  1209. option available.  Take the settings you are given, and plug them into the
  1210. dws_OVERRIDES struct.  Then call dws_DetectHardWare again.
  1211.  
  1212. Don't simply look at the capability field of the dws_DETECTRESULTS.  Its
  1213. boolean flags simply indicate whether or not we figured out everything we
  1214. needed to know about music and digitized sound.  It can't tell you, for
  1215. example, if we have a port and an IRQ level, but no DMA channel.  To
  1216. determine this, look at the baseport, digdma, and digirq fields.  If baseport
  1217. is 65535 (or 388h), then we found no digitized capability.  It's virtually
  1218. certain that none is present.  If baseport is 220h, digdma is 65535 and
  1219. digirq is 7, then we couldn't determine the DMA channel.  Ask the user!  It
  1220. beats dimming out your sound option.
  1221.  
  1222. We provide a new example program to registered users: SETUP.C, which handles
  1223. setup of sound settings, and configuration files.  It isn't pretty (using
  1224. just printf and scanf), but it illustrates some important concepts.
  1225.  
  1226.                           Reference
  1227.  
  1228. This section of the manual is broken down into several headings: The
  1229. Functions, The Errors, The Data Structures, The Utilities, and The
  1230. File Formats.
  1231.  
  1232.                         The Functions
  1233.  
  1234. Preamble
  1235. --------
  1236. There are two headers provided with the STK.  The first is for the
  1237. sound library (DWS.H for C and DWS.BI for BASIC), and the other for
  1238. the DiamondWare Timer module (DWT.H for C and DWT.BI for BASIC).
  1239.  
  1240. For Turbo Pascal version 6 and 7, there are two .TPU files provided.
  1241. Additionally, although it's not strictly necessary, DWS.PAS (which
  1242. also contains the timer module) is provided so you can see how
  1243. everything is declared.  The sound library header declares the
  1244. constants for each error the STK can generate, some bit field
  1245. constants, the data structures used by the STK, and the prototypes
  1246. of the functions.
  1247.  
  1248. This is a complete list, in alphabetical order, of functions
  1249. provided by the STK and the optional timer module.  Each function
  1250. will be listed with a general description, as well as the
  1251. declaration syntax (prototype) for C, Pascal, and BASIC (in that
  1252. order), parameters, return value, possible error conditions, and
  1253. related functions.
  1254.  
  1255. Most STK functions have a boolean return value to indicate success
  1256. (true), or error (false).  If an error occurs, call dws_ErrNo to
  1257. determine what happened.  Unless otherwise noted, the STK will
  1258. perform no action during any call which returns an error, including
  1259. modifiying structs -- all return values are undefined.
  1260.  
  1261. Most errors are provided to help you integrate the STK into your
  1262. application; once your program is stable, you should not expect to
  1263. see any errors occur.
  1264.  
  1265. All functions and all pointers are far.  All functions use the
  1266. Pascal calling convention.
  1267.  
  1268. The Optional Timer Module
  1269. -------------------------
  1270. If you have written your own hardware timer code which reprograms
  1271. the timer rate, then you don't need the DWT.  Simply don't call our
  1272. module, and it won't link into your application.
  1273.  
  1274. The DWT reprograms the hardware timer to run at a much faster rate
  1275. than normal, while keeping the DOS and BIOS clocks happy by calling
  1276. them at 18.2 Hz (like they expect).  The DWT makes the call to
  1277. dws_Update, which is required to keep the STK happy.  And DWT will
  1278. also keep time in a way useful for video games and multimedia
  1279. applications.  Even if the user has no sound hardware installed, you
  1280. can still use DWT for its timing functions without any ill effect.
  1281.  
  1282. dws_DClear
  1283.  
  1284.     Prototypes
  1285.  
  1286.     word dws_DClear(void);
  1287.     function dws_DClear : word;
  1288.     DECLARE FUNCTION dwsDClear% ALIAS "DWS_DCLEAR" ()
  1289.  
  1290.     Description
  1291.     
  1292.     This function stops all digitized sounds from playing.  Returns
  1293.     success, even if no sounds are currently playing.
  1294.  
  1295.     Parameters
  1296.     
  1297.     None.
  1298.  
  1299.     Return value
  1300.     
  1301.     Boolean success.
  1302.  
  1303.     See also
  1304.     
  1305.     dws_DPause, dws_DDiscard, 
  1306.     dws_DDiscardAO, dws_DPlay
  1307.  
  1308.     Errors
  1309.  
  1310.     dws_NOTINITED, dws_NOTSUPPORTED, dws_BUSY
  1311.  
  1312. dws_DDiscard
  1313.  
  1314.     Prototypes
  1315.  
  1316.     word dws_DDiscard(word sndnum);
  1317.     function dws_DDiscard(sndnum : word) : word;
  1318.     DECLARE FUNCTION dwsDDiscard% ALIAS
  1319.         "DWS_DDISCARD" (BYVAL sndnum%)
  1320.  
  1321.     Description
  1322.     
  1323.     This function shuts off a single sound instance.
  1324.  
  1325.     If you attempt to discard a sound which is not currently
  1326.     playing, this function will return success.
  1327.  
  1328.     Parameters
  1329.     
  1330.     sndnum is the sound you wish to discard, from the sound's
  1331.     dws_DPlay structure.
  1332.  
  1333.     Return value
  1334.  
  1335.     Boolean success.
  1336.  
  1337.     See also
  1338.  
  1339.     dws_DDiscardAO, dws_DPause, dws_DClear, dws_DPlay
  1340.  
  1341.     Errors
  1342.  
  1343.     dws_NOTINITTED, dws_NOTSUPPORTED, dws_BUSY
  1344.  
  1345. dws_DDiscardAO
  1346.  
  1347.     Prototypes
  1348.  
  1349.     word dws_DDiscardAO(byte *snd);
  1350.     function dws_DDiscardAO(snd : dws_BTPTR) : word;
  1351.     DECLARE FUNCTION dwsDDiscardAO% ALIAS
  1352.         "DWS_DDISCARDAO" (BYVAL snd&)
  1353.  
  1354.     Description
  1355.     
  1356.     This function discards all occurrences of one sound effect (.DWD
  1357.     file) that is currently playing.  If you are playing the same
  1358.     sound effect several times, this is an easy way to stop them
  1359.     all -- useful before you deallocate the sound's memory buffer,
  1360.     for example.
  1361.  
  1362.     This function requires that you specify the sound by the address
  1363.     of its buffer in memory.
  1364.  
  1365.     Note: if any sound killed by this function has a sequenced sound
  1366.     waiting to play after it, the sequenced sound will be killed
  1367.     also.
  1368.  
  1369.     Parameters
  1370.     
  1371.     snd is a pointer to the buffer storing the .DWD sound effect.
  1372.  
  1373.     Return value
  1374.  
  1375.     Boolean success.
  1376.  
  1377.     See also
  1378.  
  1379.     dws_DDiscard, dws_DPause, dws_DClear, dws_DPlay
  1380.  
  1381.     Errors
  1382.  
  1383.     dws_NOTINITTED, dws_NOTSUPPORTED, dws_D_NOTADWD,
  1384.     dws_D_NOTSUPPORTEDVER, dws_D_INTERNALERROR, dws_BUSY
  1385.  
  1386. dws_DetectHardWare
  1387.  
  1388.     Prototypes
  1389.  
  1390.         word dws_DetectHardWare(dws_DETECTOVERRIDES *dov,
  1391.     dws_DETECTRESULTS *dr); function dws_DetectHardWare(dov :
  1392.     dws_DOPTR; dr :dws_DRPTR) : word; DECLARE FUNCTION
  1393.     dwsDetectHardWare% ALIAS "DWS_DETECTHARDWARE" (SEG dov AS
  1394.         dwsDETECTOVERRIDES, SEG dr AS dwsDETECTRESULTS)
  1395.  
  1396.     Description
  1397.  
  1398.     This is the STK's hardware autodetect.  It detects card
  1399.     settings, or verifies settings you put in dov.  Upon return, dr
  1400.     will be filled with the autodetection results.  DiamondWare
  1401.     recommends calling this function at the beginning of your
  1402.     program, each time it is run, so that if the user changes
  1403.     hardware settings between runs, your program will still work.
  1404.  
  1405.     Parameters
  1406.  
  1407.     dov is a pointer to a dws_DETECTOVERRIDES struct.  Set every
  1408.     field with either a 65535 (to autodetect), or an override (user
  1409.     setting).  User setting values will be accepted on faith (sort of).
  1410.  
  1411.     dr is a pointer to a dws_DETECTRESULTS structure, where the
  1412.     function will return its results.
  1413.  
  1414.     The reserved array in this struct holds important information;
  1415.     if you write the contents of the struct out to a file, write the
  1416.     entire struct!  dws_Init requires all of this information;
  1417.     without it, the STK could crash the computer.
  1418.  
  1419.     The bitfield capability indicates supported features:  
  1420.  
  1421.     0                                       //no sound hardware
  1422.     dws_capability_FM                       //music
  1423.     dws_capability_DIG                      //digitized sounds
  1424.     dws_capability_FM | dws_capability_DIG  //Both
  1425.  
  1426.     Return value
  1427.  
  1428.     Boolean success.
  1429.  
  1430.     See also
  1431.  
  1432.     dws_Init, dws_Kill
  1433.  
  1434.     Errors
  1435.  
  1436.     dws_ALREADYINITTED, dws_DetectHardware_UNSTABLESYSTEM, 
  1437.     dws_DetectHardware_BADBASEPORT, dws_DetectHardware_BADDMA, 
  1438.     dws_DetectHardware_BADIRQ, dws_IRQDISABLED
  1439.  
  1440.     If the machine becomes unstable more than twice, please contact
  1441. DiamondWare!
  1442.  
  1443. dws_DGetRate
  1444.  
  1445.     Prototypes
  1446.  
  1447.     word dws_DGetRate(word *result);
  1448.     function dws_DGetRate(result : dws_WDPTR) : word;
  1449.     DECLARE FUNCTION dwsDGetRate% ALIAS
  1450.         "DWS_DGETRATE" (SEG result%)
  1451.  
  1452.     Description
  1453.  
  1454.     This function returns the sampling rate to which the hardware is
  1455.     currently set.
  1456.  
  1457.     Parameters
  1458.  
  1459.     result is a pointer to the variable that will store the current
  1460.     sampling rate.
  1461.  
  1462.     Return value
  1463.  
  1464.     Boolean success.
  1465.  
  1466.     See also
  1467.  
  1468.     dws_DGetRateFromDWD, dws_DSetRate
  1469.  
  1470.     Errors
  1471.  
  1472.     dws_NOTINITTED, dws_NOTSUPPORTED, dws_BUSY
  1473.  
  1474. dws_DGetRateFromDWD
  1475.  
  1476.     Prototypes
  1477.  
  1478.     word dws_DGetRateFromDWD(byte *snd, word *result);
  1479.     dws_DGetRateFromDWD(snd : dws_BTPTR; result : dws_WDPTR) : word;
  1480.     DECLARE FUNCTION dwsDGetRateFromDWD% ALIAS "DWS_DGETRATEFROMDWD" 
  1481.         (BYVAL snd&, SEG result%)
  1482.  
  1483.     Description
  1484.  
  1485.     This function returns the sampling rate at which a .DWD file was
  1486.     recorded.
  1487.  
  1488.     Note: this function will work before dws_Init is called.
  1489.  
  1490.     Parameters
  1491.     
  1492.     snd is a pointer to a buffer containing a .DWD file.
  1493.  
  1494.     result is a pointer to a variable that will store the recorded
  1495.     sampling rate.
  1496.  
  1497.     Return value
  1498.  
  1499.     Boolean success.
  1500.  
  1501.     See also
  1502.  
  1503.     dws_DGetRate, dws_DSetRate
  1504.  
  1505.     Errors
  1506.  
  1507.     dws_D_NOTADWD, dws_D_NOTSUPPORTEDVER, dws_BUSY
  1508.  
  1509. dws_DPause
  1510.  
  1511.     Prototypes
  1512.  
  1513.     word dws_DPause(void);
  1514.     function dws_DPause : word;
  1515.     DECLARE FUNCTION dwsDPause% ALIAS "DWS_DPAUSE" ()
  1516.  
  1517.     Description
  1518.  
  1519.     This function pauses all digitized sound playback.
  1520.  
  1521.     Note: all calls after the first will have no effect until
  1522.     dws_DUnPause is called.  The STK does not maintain a "pause
  1523.     count".
  1524.  
  1525.     Parameters
  1526.  
  1527.     None.
  1528.  
  1529.     Return value
  1530.     
  1531.     Boolean success.
  1532.  
  1533.     See also
  1534.  
  1535.     dws_DUnPause, dws_Discard, dws_DiscardAO, dws_DClear
  1536.  
  1537.     Errors
  1538.  
  1539.     dws_NOTINITED, dws_NOTSUPPORTED, dws_BUSY
  1540.  
  1541. dws_DPlay
  1542.  
  1543.     Prototypes
  1544.  
  1545.     word dws_DPlay(dws_DPLAY *dplay);
  1546.     function dws_DPlay(dplay : dws_DPPTR) : word;
  1547.     DECLARE FUNCTION dwsDPlay% ALIAS "DWS_DPLAY"(SEG
  1548.         dplay AS dwsDPLAY)
  1549.  
  1550.     Description
  1551.     
  1552.     This function plays a digitized sound.
  1553.  
  1554.     Parameters
  1555.     
  1556.     dplay is a pointer to a filled dws_DPLAY struct, which contains:
  1557.  
  1558.         snd      pointer to a buffer with a .DWD
  1559.         count    number of times to play; 0 means repeat indefinitely
  1560.         priority relative to other sounds; low priority snds may drop
  1561.         soundnum unique ID -- returned by the STK
  1562.         presnd   ID of sound to sequence after; 0 means don't seq
  1563.  
  1564.     Return value
  1565.  
  1566.     Boolean success.
  1567.  
  1568.     See also
  1569.  
  1570.     dws_DDiscard, dws_DDiscardAO, dws_DClear, dws_DSoundStatus
  1571.  
  1572.     Errors
  1573.  
  1574.     dws_NOTINITTED, dws_NOTSUPPORTED, dws_D_NOTADWD,
  1575.     dws_D_NOTSUPPORTEDVER, dws_D_INTERNALERROR,
  1576.     dws_DPlay_NOSPACEFORSOUND, dws_BUSY
  1577.  
  1578. dws_DSetRate
  1579.  
  1580.     Prototypes
  1581.  
  1582.     word dws_DSetRate(word frequency);
  1583.     function dws_DSetRate(frequency : word) : word;
  1584.     DECLARE FUNCTION dwsDSetRate% ALIAS
  1585.         "DWS_DSETRATE" (BYVAL frequency%)
  1586.  
  1587.     Description
  1588.  
  1589.     This function sets the digitized sampling rate.  If sounds are
  1590.     currently playing, this might sound weird.    We recommend that
  1591.     you change rates only when nothing's playing.
  1592.  
  1593.     Note: some sound boards don't support every rate allowed by the
  1594.     Sound Blasters.  Many sound boards will produce an audible click
  1595.     when the rate is changed on the fly.
  1596.  
  1597.     The STK supports sampling rates from 4 KHz to 24 KHz.
  1598.  
  1599.     Parameters
  1600.  
  1601.     frequency is the new sampling rate to use.
  1602.  
  1603.     Return value
  1604.  
  1605.     Boolean success.
  1606.  
  1607.     See also
  1608.  
  1609.     dws_DGetRate, dws_DGetRateFromDWD
  1610.  
  1611.     Errors
  1612.  
  1613.     dws_NOTINITTED, dws_NOTSUPPORTED, dws_DSetRate_FREQTOLOW, 
  1614.     dws_DSetRate_FREQTOHIGH, dws_BUSY
  1615.  
  1616. dws_DSoundStatus
  1617.  
  1618.     Prototypes
  1619.  
  1620.     word dws_DSoundStatus(word sndnum, word *result); function
  1621.     dws_DSoundStatus(sndnum : word; result : dws_WDPTR) : word;
  1622.     DECLARE FUNCTION dwsDSoundStatus% ALIAS "DWS_DSOUNDSTATUS"(BYVAL
  1623.         sndnum%, SEG result%)
  1624.  
  1625.     Description
  1626.  
  1627.     Internally, the STK stores each sound in a slot.  Each slot can
  1628.     hold up to two sounds -- an active sound and a sequenced sound
  1629.     (which becomes active when the currently active sound ends).
  1630.     The slot is identified by the ID of the sound playing in it.
  1631.  
  1632.     This function queries the status of a slot.
  1633.  
  1634.     Parameters
  1635.     
  1636.     sndnum is the sound's unique ID.
  1637.  
  1638.     result is a pointer to a variable to hold the returned status: 
  1639.  
  1640.     0                                         //no sound with this ID
  1641.     dws_DSTATUSCURRENT                        //sound is currently playing
  1642.     dws_DSTATUSSEQUENCED                      //sound is sequenced
  1643.     dws_DSTATUSCURRENT | dws_DSTATUSSEQUENCED //both
  1644.  
  1645.     For a slot to contain a sequenced sound, it must also hold a
  1646.     playing sound.  If you ever encounter a case where a slot
  1647.     contains only a sequenced sound, please report it to
  1648.     DiamondWare.
  1649.  
  1650.     Return value
  1651.  
  1652.     Boolean success.
  1653.  
  1654.     See also
  1655.  
  1656.     dws_DPlay
  1657.  
  1658.     Errors
  1659.  
  1660.     dws_NOTINITED, dws_NOTSUPPORTED, dws_BUSY
  1661.  
  1662. dws_DUnPause
  1663.  
  1664.     Prototypes
  1665.  
  1666.     word dws_DUnPause(void);
  1667.     function dws_DUnPause : word;
  1668.     DECLARE FUNCTION dwsDUnPause% ALIAS "DWS_DUNPAUSE" ()
  1669.  
  1670.     Description
  1671.  
  1672.     This function resumes digitized playback, if it was previously
  1673.     paused by dws_DPause.
  1674.  
  1675.     All sounds will continue where they left off.
  1676.  
  1677.     Note: all calls after the first will have no effect until
  1678.     dws_DPause is called again.  The STK does not maintain a "pause
  1679.     count".
  1680.  
  1681.     Parameters
  1682.  
  1683.     None.
  1684.  
  1685.     Return value
  1686.  
  1687.     Boolean success.
  1688.  
  1689.     See also
  1690.  
  1691.     dws_DPause
  1692.  
  1693.     Errors
  1694.  
  1695.     dws_NOTINITED, dws_NOTSUPPORTED, dws_BUSY
  1696.  
  1697. dws_ErrNo
  1698.  
  1699.     Prototypes
  1700.  
  1701.     word dws_ErrNo(void);
  1702.     function dws_ErrNo : word;
  1703.     DECLARE FUNCTION dwsErrNo% ALIAS "DWS_ERRNO" ()
  1704.  
  1705.     Description
  1706.     
  1707.     This function returns the last error triggered by an STK
  1708.     function.  Call it after any STK function returns false as its
  1709.     boolean success indicator.
  1710.  
  1711.     Successful STK calls do not affect the return value of dws_ErrNo.
  1712.  
  1713.     Parameters
  1714.  
  1715.     None.
  1716.  
  1717.     Return value
  1718.     
  1719.     The last STK error.
  1720.  
  1721.     See also
  1722.  
  1723.     None.
  1724.  
  1725.     Errors
  1726.  
  1727.     None.
  1728.  
  1729. dws_Init
  1730.  
  1731.     Prototypes
  1732.  
  1733.     word dws_Init(dws_DETECTRESULTS *dr, dws_IDEAL *ideal); function
  1734.     dws_Init(dr : dws_DRPTR; ideal : dws_IDPTR) : word; DECLARE
  1735.         FUNCTION
  1736.     dwsInit% ALIAS "DWS_INIT" (SEG dr AS dwsDETECTRESULTS, SEG ideal
  1737.         AS dwsIDEAL)
  1738.  
  1739.     Description
  1740.  
  1741.     This function configures and initializes the hardware and the
  1742.     STK internals.  Most STK calls won't work until after this call.
  1743.  
  1744.     The exceptions are dws_Update, dws_DetectHardWare, dws_ErrNo,
  1745.     and dws_DGetRateFromDWD.
  1746.  
  1747.     Parameters
  1748.     
  1749.     dr is a pointer to a dws_DETECTRESULTS struct that has been
  1750.     filled in by a call to dws_DetectHardWare.
  1751.  
  1752.     ideal is a pointer to a dws_IDEAL structure, which you must fill
  1753.     in with your requested settings.  The programmer might not want
  1754.     the user's sound board running to its limit, and/or the user's
  1755.     sound board may not support every feature of the STK.
  1756.  
  1757.     Note: the STK supports sample rates from 4 KHz to 24 KHz.
  1758.  
  1759.     Return value
  1760.     
  1761.     Boolean success.
  1762.  
  1763.     See also
  1764.  
  1765.     dws_DetectHardWare, dws_Kill, dws_Update
  1766.  
  1767.     Errors
  1768.  
  1769.     dws_ALREADYINITTED, dws_IRQDISABLED
  1770.  
  1771. dws_Kill
  1772.  
  1773.     Prototypes
  1774.  
  1775.     word dws_Kill(void);
  1776.     function dws_Kill : word;
  1777.     DECLARE FUNCTION dwsKill% ALIAS "DWS_KILL"()
  1778.  
  1779.     Description
  1780.  
  1781.     This function closes down the STK.  You must call it before your
  1782.     program terminates.
  1783.  
  1784.     Note: make sure you cover every exit path from your program,
  1785.     including DOS critical errors!  Failure to do so will leave the
  1786.     machine in a bad state.  The sound board will make noise
  1787.     forever.  The DMA controller will continue transferring.  The
  1788.     sound hardware will continue to generate IRQ's.  When the next
  1789.     program is loaded, it will overwrite the STK's Interrupt Service
  1790.     Routine (ISR)--and the machine will crash.
  1791.  
  1792.     Parameters
  1793.  
  1794.     None.
  1795.  
  1796.     Return value
  1797.     
  1798.     Boolean success.
  1799.  
  1800.     See also
  1801.  
  1802.     dws_Init, dws_DetectHardWare, dws_Update
  1803.  
  1804.     Errors
  1805.  
  1806.     dws_NOTINITTED, dws_Kill_CANTUNHOOKISR, dws_IRQDISABLED, dws_BUSY
  1807.  
  1808.     If the STK can't unhook its ISR, it probably means the user
  1809.     installed a TSR which handles the sound board's IRQ.  Whatever
  1810.     it accomplished(?), it's now preventing the STK from properly
  1811.     unhooking itself.  Tell the user to get rid of it, and call
  1812.     dws_Kill again.
  1813.  
  1814. dws_MClear
  1815.  
  1816.     Prototypes
  1817.  
  1818.     word dws_MClear(void);
  1819.     function dws_MClear : word;
  1820.     DECLARE FUNCTION dwsMClear% ALIAS "DWS_MCLEAR" ()
  1821.  
  1822.     Description
  1823.  
  1824.     This function stops music playback.
  1825.  
  1826.     Parameters
  1827.         
  1828.     None.
  1829.  
  1830.     Return value
  1831.     
  1832.     Boolean success.
  1833.  
  1834.     See also
  1835.  
  1836.     dws_MPause, dws_MPlay
  1837.  
  1838.     Errors
  1839.  
  1840.     dws_NOTINITED, dws_NOTSUPPORTED, dws_BUSY
  1841.  
  1842. dws_MPause
  1843.  
  1844.     Prototypes
  1845.  
  1846.     word dws_MPause(void);
  1847.     function dws_MPause : word;
  1848.     DECLARE FUNCTION dwsMPause% ALIAS "DWS_MPAUSE" ()
  1849.  
  1850.     Description
  1851.  
  1852.     This function pauses music playback.
  1853.  
  1854.     Note: all calls after the first will have no effect until
  1855.     dws_MUnPause is called.  The STK does not maintain a "pause
  1856.     count".
  1857.  
  1858.     Parameters
  1859.     
  1860.     None.
  1861.  
  1862.     Return value
  1863.  
  1864.     Boolean success.
  1865.  
  1866.     See also
  1867.  
  1868.     dws_MUnPause, dws_MClear, dws_MPlay
  1869.  
  1870.     Errors
  1871.  
  1872.     dws_NOTINITED, dws_NOTSUPPORTED, dws_BUSY
  1873.  
  1874. dws_MPlay
  1875.  
  1876.     Prototypes
  1877.  
  1878.     word dws_MPlay(dws_MPLAY *mplay);
  1879.     function dws_MPlay(mplay : dws_MPPTR) : word;
  1880.     DECLARE FUNCTION dwsMPlay% ALIAS "DWS_MPLAY" (SEG mplay AS
  1881.         dwsMPLAY)
  1882.  
  1883.     Description
  1884.  
  1885.     This function starts playing a song.
  1886.  
  1887.     Parameters
  1888.  
  1889.     mplay is a pointer to a dws_MPLAY struct, which you must fill
  1890.     in.  The fields are:
  1891.  
  1892.     track  pointer to a buffer which contains a .DWM file.
  1893.     count  number of times to play; 0 means repeat indefinitely.
  1894.  
  1895.     Return value
  1896.  
  1897.     Boolean success.
  1898.  
  1899.     See also
  1900.  
  1901.     dws_MClear, dws_MPause, dws_MSongStatus, dws_BUSY
  1902.  
  1903.     Errors
  1904.  
  1905.     dws_NOTINITED, dws_NOTSUPPORTED, dws_MPlay_NOTADWM, 
  1906.     dws_MPlay_NOTSUPPORTEDVER, dws_MPlay_INTERNALERROR
  1907.  
  1908. dws_MSongStatus
  1909.  
  1910.     Prototypes
  1911.  
  1912.     word dws_MSongStatus(word *status);
  1913.     function dws_MSongStatus(result : dws_WDPTR) : word;
  1914.     DECLARE FUNCTION dwsMSongStatus% ALIAS = "DWS_MSONGSTATUS" (SEG
  1915.         result%)
  1916.  
  1917.     Description
  1918.  
  1919.     This function returns the status of the music playback engine.
  1920.  
  1921.     Parameters
  1922.  
  1923.     result is a pointer to a variable to hold the returned status:
  1924.  
  1925.     0                                              //no song loaded
  1926.     dws_MSONGSTATUSPLAYING                         //song playing
  1927.     dws_MSONGSTATUSPAUSED                          //no song loaded,
  1928.                                                      STK paused
  1929.     dws_MSONGSTATUSPLAYING | dws_MSONGSTATUSPAUSED //Song loaded but
  1930.                                                      paused
  1931.  
  1932.     Return value
  1933.  
  1934.     Boolean success.
  1935.  
  1936.     See also
  1937.  
  1938.     dws_MPlay
  1939.  
  1940.     Errors
  1941.  
  1942.     dws_NOTINITED, dws_NOTSUPPORTED, dws_BUSY
  1943.  
  1944. dws_MUnPause
  1945.  
  1946.     Prototypes
  1947.  
  1948.     word dws_MUnPause(void);
  1949.     function dws_MUnPause : word;
  1950.     DECLARE FUNCTION dwsMUnPause% ALIAS "DWS_MUNPAUSE" ()
  1951.  
  1952.     Description
  1953.     
  1954.     This function unpauses music paused by dws_MPause.  The music
  1955.     will continue where it left off, save that any sustaining notes
  1956.     will not start until their next key on.
  1957.  
  1958.     Note: all calls after the first will have no effect until
  1959.     dws_MPause is called again.  The STK does not maintain a "pause
  1960.     count".
  1961.  
  1962.     Parameters
  1963.  
  1964.     None.
  1965.  
  1966.     Return value
  1967.  
  1968.     Boolean success.
  1969.  
  1970.     See also
  1971.  
  1972.     dws_MPause
  1973.  
  1974.     Errors
  1975.  
  1976.     dws_NOTINITED, dws_NOTSUPPORTED, dws_BUSY
  1977.  
  1978. dws_Update
  1979.  
  1980.     Prototypes
  1981.  
  1982.     void __loadds __saveregs dws_Update(void);
  1983.     procedure dws_Update;
  1984.     SUB dwsUpdate ALIAS "DWS_UPDATE" ()
  1985.  
  1986.     Description
  1987.  
  1988.     This function keeps the STK going.  Call it regularly and frequently.
  1989.  
  1990.     If you're using the DWT, don't call dws_Update!  Everything has
  1991.     been taken care of.
  1992.  
  1993.     If you are using your own timer handler, you need to call
  1994.     dws_Update every time you get your interrupt.  dws_Update will
  1995.     load the registers it needs, and restore the caller's registers
  1996.     before returning.  Note that this function is to be called, not
  1997.     jumped to.  It returns with a retf, not an iret.
  1998.  
  1999.     Parameters
  2000.  
  2001.     None.
  2002.  
  2003.     Return value
  2004.  
  2005.     None.
  2006.  
  2007.     See also
  2008.  
  2009.     dws_Init, dwt_Init, dws_Kill, dwt_Kill
  2010.  
  2011.     Errors
  2012.  
  2013.     None
  2014.  
  2015. dws_XDig
  2016.  
  2017.     Prototypes
  2018.  
  2019.     word dws_XDig(word volume);
  2020.     function dws_XDig(volume : word) : word;
  2021.     DECLARE FUNCTION dwsXDig% ALIAS "DWS_XDIG" (BYVAL volume%)
  2022.  
  2023.     Description
  2024.     
  2025.     This function sets the digitized volume of the mixer.
  2026.  
  2027.     Note: dws_Init sets the digital volume to maximum.
  2028.  
  2029.     Parameters
  2030.  
  2031.     volume is the digitized sound level (0=min, 255=max).
  2032.  
  2033.     Return value
  2034.     
  2035.     Boolean success.
  2036.  
  2037.     See also
  2038.  
  2039.     dws_XMusic, dws_XMaster
  2040.  
  2041.     Errors
  2042.  
  2043.     dws_NOTINITTED, dws_NOTSUPPORTED, dws_X_BADINPUT, dws_BUSY
  2044.  
  2045. dws_XMaster
  2046.  
  2047.     Prototypes
  2048.  
  2049.     word dws_XMaster(word volume);
  2050.     function dws_XMaster(volume : word) : word;
  2051.     DECLARE FUNCTION dwsXMaster% ALIAS "DWS_XMASTER" (BYVAL volume%)
  2052.  
  2053.     Description
  2054.  
  2055.     This function sets the overall volume of the mixer.
  2056.  
  2057.     Note: dws_Init sets the master volume to maximum.
  2058.  
  2059.     Parameters
  2060.     
  2061.     volume is the master sound level (0=min, 255=max).
  2062.  
  2063.     Return value
  2064.     
  2065.     Boolean success.
  2066.  
  2067.     See also
  2068.  
  2069.     dws_XDig, dws_XMusic
  2070.  
  2071.     Errors
  2072.  
  2073.     dws_NOTINITTED, dws_NOTSUPPORTED, dws_X_BADINPUT, dws_BUSY
  2074.  
  2075. dws_XMusic
  2076.  
  2077.     Prototypes
  2078.  
  2079.     word dws_XMusic(word volume);
  2080.     function dws_XMusic(volume : word) : word;
  2081.     DECLARE FUNCTION dwsXMusic% ALIAS "DWS_XMUSIC" (BYVAL volume%)
  2082.  
  2083.     Description
  2084.  
  2085.     This function sets the music volume of the mixer.
  2086.  
  2087.     Note: dws_Init sets the music volume to maximum.
  2088.  
  2089.     Parameters
  2090.  
  2091.     volume is the music sound level (0=min, 255=max).
  2092.  
  2093.     Return value
  2094.  
  2095.     Boolean success.
  2096.  
  2097.     See also
  2098.  
  2099.     dws_XDig, dws_XMaster
  2100.  
  2101.     Errors
  2102.  
  2103.     dws_NOTINITTED, dws_NOTSUPPORTED, dws_X_BADINPUT, dws_BUSY
  2104.  
  2105. dwt_Init
  2106.  
  2107.     Prototypes
  2108.  
  2109.     void dwt_Init(word rate);
  2110.     procedure dwt_Init(rate : word);
  2111.     DECLARE SUB dwtInit ALIAS "DWT_INIT" (BYVAL rate%)
  2112.  
  2113.     Description
  2114.  
  2115.     This function initializes the timer hardware and DWT internals.
  2116.  
  2117.     Call this only if you're using the DWT.  Use the DWT only if you
  2118.     aren't reprogramming the hardware timer.
  2119.  
  2120.     None of the DWT functions will work until this function is called.
  2121.  
  2122.     Parameters
  2123.     
  2124.     rate is one of the four constants:
  2125.         dwt_18_2HZ
  2126.         dwt_36_4HZ
  2127.         dwt_72_8HZ
  2128.         dwt_145_6HZ
  2129.  
  2130.     Return value
  2131.  
  2132.     None.
  2133.  
  2134.     See also
  2135.  
  2136.     dws_Update, dwt_Kill, dwt_MasterTick
  2137.  
  2138. dwt_Kill
  2139.  
  2140.     Prototypes
  2141.  
  2142.     void dwt_Kill(void);
  2143.     procedure dwt_Kill;
  2144.     DECLARE SUB dwtKill ALIAS "DWT_KILL" ()
  2145.  
  2146.     Description
  2147.     
  2148.     This function closes down the DWT.  If you used the DWT, you
  2149.     must call dwt_Kill before your program terminates.
  2150.  
  2151.     Note: make sure you cover every exit path from your program,
  2152.     including DOS critical errors!  Failure to do so will leave the
  2153.     machine in a bad state.  When the next program is loaded, it
  2154.     will overwrite the DWT's Interrupt Service Routine (ISR)--and
  2155.     the machine will crash.
  2156.  
  2157.     Parameters
  2158.  
  2159.     None.
  2160.  
  2161.     Return value
  2162.  
  2163.     None.
  2164.  
  2165.     See also
  2166.  
  2167.     dws_Update, dwt_Init
  2168.  
  2169. dwt_MasterTick
  2170.  
  2171.     Prototypes
  2172.  
  2173.     dword dwt_MasterTick(void);
  2174.     dwt_MasterTick : longint;
  2175.     DECLARE FUNCTION dwtMasterTick& ALIAS "DWT_MASTERTICK" ()
  2176.  
  2177.     Description
  2178.     
  2179.     This function queries the value of the master timer.
  2180.  
  2181.     The master timer is reset to 0 in dwt_Init, and is incremented
  2182.     at the DWT timer rate.
  2183.  
  2184.     Parameters
  2185.  
  2186.     None.
  2187.  
  2188.     Return value
  2189.     
  2190.     Number of clock ticks since DWT was initialized.
  2191.  
  2192.     See also
  2193.  
  2194.     dwt_Init, dwt_Pause, dwt_UnPause
  2195.  
  2196. dwt_Pause
  2197.  
  2198.     Prototypes
  2199.  
  2200.     void dwt_Pause(void);
  2201.     procedure dwt_Pause;
  2202.     DECLARE SUB dwtPause ALIAS "DWT_INIT" ()
  2203.  
  2204.     Description
  2205.     
  2206.     This function pauses the master timer.
  2207.  
  2208.     Note: this does not effect music or sound playback.
  2209.  
  2210.     Note: all calls after the first will have no effect until
  2211.     dwt_UnPause is called.  The DWT does not maintain a "pause
  2212.     count".
  2213.  
  2214.     Parameters
  2215.     
  2216.     None.
  2217.  
  2218.     Return value
  2219.     
  2220.     None.
  2221.  
  2222.     See also
  2223.  
  2224.     dwt_MasterTick, dwt_UnPause
  2225.  
  2226. dwt_UnPause
  2227.  
  2228.     Prototypes
  2229.  
  2230.     void dwt_UnPause(void);
  2231.     procedure dwt_UnPause;
  2232.     DECLARE SUB dwtUnPause ALIAS "DWT_KILL" ()
  2233.  
  2234.     Description
  2235.     
  2236.     This function unpauses the master timer, if it was previously
  2237.     paused by dwt_Pause.
  2238.  
  2239.     Note: all calls after the first will have no effect until
  2240.     dwt_Pause is called again.  The STK does not maintain a "pause
  2241.     count"
  2242.  
  2243.     Parameters
  2244.     
  2245.     None.
  2246.  
  2247.     Return value
  2248.     
  2249.     None.
  2250.  
  2251.     See also
  2252.  
  2253.     dwt_Pause, dwt_MasterTick
  2254.         
  2255.                                The Errors
  2256.  
  2257. About the Error Listing
  2258. -----------------------
  2259. This section discusses every possible STK error in numerical order.
  2260. See The Functions to find the complete list of errors which may be
  2261. flagged by any given function.
  2262.  
  2263. 0.  dws_EZERO
  2264. There was no error.  You didn't need to call dws_ErrNo.
  2265.  
  2266. 1.  dws_NOTINITTED
  2267. The STK was not initialized when you called an STK function.
  2268.  
  2269. 2.  dws_ALREADYINITTED
  2270. This call cannot be made after the STK is initialized.
  2271.  
  2272. 3.  dws_NOTSUPPORTED
  2273. The installed hardware doesn't support the requested feature (music
  2274. or sound).
  2275.  
  2276. 4.  dws_DetectHardware_UNSTABLESYSTEM
  2277. This system is now unstable.  Please report this to DiamondWare.
  2278.  
  2279. 5.  dws_DetectHardware_BADBASEPORT
  2280. 6.  dws_DetectHardware_BADDMA
  2281. 7.  dws_DetectHardware_BADIRQ
  2282. You tried to override the autodetect with an irrational value for
  2283. base port, DMA channel, or IRQ level, respectively.
  2284.  
  2285. 8.  dws_Kill_CANTUNHOOKISR
  2286. After the STK initialized, the user installed a TSR which hooked the
  2287. sound board's interrupt vector.  The STK can't shut down cleanly.
  2288. Tell the user to kill the TSR.  Then call dws_Kill again.
  2289.  
  2290. 9.  dws_X_BADINPUT
  2291. You attempted to set a mixer level (digitized, music, or master) to
  2292. a value outside the range 0-255.
  2293.  
  2294. 10.  dws_D_NOTADWD
  2295. The buffer does not contain a valid .DWD file.
  2296.  
  2297. 11.  dws_D_NOTSUPPORTEDVER
  2298. This .DWD file is the wrong version.  Please reconvert using the
  2299. VOC2DWD which came with this version of the STK.
  2300.  
  2301. 12.  dws_D_INTERNALERROR
  2302. The STK encountered an invalid internal state.  Please report this
  2303. to DiamondWare.
  2304.  
  2305. 13.  dws_DPlay_NOSPACEFORSOUND
  2306. You attempted to play a low-priority sound, but all slots were in
  2307. use.  Try increasing ideal.dignvoices.  If this error occurs with
  2308. that set to 16, you're playing too many sounds too fast.  Note: this
  2309. one is a warning.  It's reasonable to flag this error occasionally.
  2310. But if it occurs immediately, or consistently, try calling dws_DPlay
  2311. less often.
  2312.  
  2313. 14.  dws_DSetRate_FREQTOLOW
  2314. 15.  dws_DSetRate_FREQTOHIGH
  2315. You attempted to set the sampling rate to an invalid frequency.  The
  2316. STK supports sampling rates from 4 KHz to 24 KHz.
  2317.  
  2318. 16.  dws_MPlay_NOTADWM
  2319. The buffer does not contain a valid .DWM file.
  2320.  
  2321. 17.  dws_MPlay_NOTSUPPORTEDVER
  2322. This .DWM file is the wrong version.  Please reconvert using the
  2323. MID2DWM which came with this version of the STK.
  2324.  
  2325. 18.  dws_MPlay_INTERNALERROR
  2326. The STK encountered an invalid internal state.  Please report this
  2327. to DiamondWare.
  2328.  
  2329. 19.  dws_BUSY
  2330. The STK is busy now.  Please call again later.    This error can only
  2331. occur if you're calling the STK from an interrupt handler.
  2332.  
  2333. 20.  dws_IRQDISABLED
  2334. You disabled IRQ's (with the CLI instruction).  IRQ's must be
  2335. enabled (with the STI instruction).
  2336.  
  2337.                         The Data Structures
  2338.  
  2339. Preamble
  2340. --------
  2341. In this section, the data structures are laid out in table form.
  2342. This is done in the hope that it's easier to read than compiler
  2343. declarations.  Obviously, you can read the actual source files if
  2344. you wish.
  2345.  
  2346. Note to Pascal programmers: the following types were created to
  2347. allow the declaration of subroutines which take far pointers to
  2348. their parameters.  Declaring a function:
  2349.  
  2350. function FooBar(var x: word);
  2351.  
  2352. passes a near pointer.  The STK expects far pointers.
  2353.  
  2354. dws_DOPTR = ^dws_DETECTOVERRIDES;
  2355. dws_DRPTR = ^dws_DETECTRESULTS;
  2356. dws_IDPTR = ^dws_IDEAL;
  2357. dws_DPPTR = ^dws_DPLAYREC;
  2358. dws_MPPTR = ^dws_MPLAYREC;
  2359. dws_WDPTR = ^word;
  2360. dws_BTPTR = ^byte;
  2361.  
  2362.  
  2363. The dws_DETECTOVERRIDES struct
  2364.  
  2365. Name      Size    I/O     Description
  2366. ------------------------------------------------------
  2367. baseport  2       input   base address of sound board
  2368. digdma    2       input   DMA channel
  2369. digirq    2       input   IRQ level
  2370. reserved  10      -na-    undocumented
  2371.  
  2372.  
  2373. The dws_DETECTRESULTS struct
  2374.  
  2375. Name        Size    I/O     Description
  2376. -------------------------------------------------------------
  2377. baseport    2       output  base address of sound board
  2378. capability  2       output  bitfield of supported features
  2379. mustyp      2       output  0=none, 1=OPL2
  2380. musnchan    2       output  *1=mono
  2381. musnvoice   2       output  *number of melody voices
  2382. dignbits    2       output  +8=8 bits
  2383. dignchan    2       output  +1=mono
  2384. digdma      2       output  +digitized DMA channel
  2385. digirq      2       output  +digitized IRQ level
  2386. mixtyp      2       output  mixer type (1 software, 2+ H/W)
  2387. reserved    44      -na-    undocumented
  2388.  
  2389. * if (capability & dws_capability_FM)
  2390. + if (capability & dws_capability_DIG)
  2391.  
  2392. The dws_IDEAL struct
  2393.  
  2394. Name        Size    I/O     Description
  2395. ----------------------------------------------------------------
  2396. musictyp    2       input   music type (0 none, 1 FM)
  2397. digtyp      2       input   digitzed type (0 none, 8 8-bit dig)
  2398. digrate     2       input   sampling rate, in Hz
  2399. dignvoices  2       input   number of voices (up to 16)
  2400. dignchan    2       input   1=mono
  2401. reserved    6       -na-    undocumented
  2402.  
  2403.  
  2404. The dws_DPLAY struct
  2405.  
  2406. Name      Size      I/O       Description
  2407. -----------------------------------------------------------------
  2408. snd       4         input     pointer to buffer with .DWD in it
  2409. count     2         input     # times to play (0=infinite loop)
  2410. priority  2         input     higher numbers are higher priority
  2411. presnd    2         input     soundnum to sequence after
  2412. soundnum  2         output    unique ID
  2413. reserved  20        -na-      undocumented
  2414.  
  2415.  
  2416. The dws_MPlay struct
  2417.  
  2418. Name      Size      I/O       Description
  2419. ----------------------------------------------------------------
  2420. track     4         input     pointer to buffer with .DWM in it
  2421. count     2         input     # times to play (0=infinite loop)
  2422. reserved  10        -na-      undocumented
  2423.  
  2424.                          The Utilities
  2425.  
  2426. PLAYDWM
  2427. -------
  2428. PLAYDWM is a simple program to play .DWM music files.  Full source
  2429. is included with the STK.  Usage is:
  2430.  
  2431. PLAYDWM songname.dwm
  2432.  
  2433. You must type the full filename, including the .DWM.
  2434.  
  2435. PLAYDWD
  2436. -------
  2437. PLAYDWD is a simple program to play .DWD sound effect files.  Full
  2438. source is included with the STK.  Usage is:
  2439.  
  2440. PLAYDWD soundfx.dwd
  2441.  
  2442. You must type the full filename, including the .DWD.
  2443.  
  2444. FINDSB
  2445. ------
  2446. FINDSB is provided as both a simple example of how to use the STK,
  2447. and as a useful program in its own right.  Full source is included
  2448. with the STK.  It will find and print out the user's sound board
  2449. settings.  Usage is:
  2450.  
  2451. FINDSB
  2452.  
  2453. MID2DWM
  2454. -------
  2455. MID2DWM converts type 1 standard MIDI files from .MID format to .DWM
  2456. format.  It is strictly a command-line utility.  Usage is:
  2457.  
  2458. MID2DWM <rate> <midifile>[.MID] <instrfile>[.IBK] [outfile[.DWM]]
  2459.  
  2460. rate is the frequency, at which STK will get its "heartbeat" call
  2461. during run-time.  In general, the higher the rate, the more natural
  2462. the music will sound (to a limit).  If your music was performed by a
  2463. human, there are many nuances of timing which will be lost at lower
  2464. rates.
  2465.  
  2466. Note: if your program is running in a Windows DOS box, 145.6 Hz will
  2467. not work correctly (Windows will simply refuse to call you that
  2468. fast, and so the music will play slower than normal).
  2469.  
  2470. The STK includes an optional timer module which is capable of four
  2471. rates: 18.2, 36.4, 72.8, and 145.6 Hz.  If you use your own timer
  2472. code, then tell MID2DWM the rate it runs at; MID2DWM will work at
  2473. any rate.  If you're using the code supplied in the STK, use one of
  2474. those four rates only.
  2475.  
  2476. midifile is the name of the source file for the music, in MIDI type
  2477. 1 format.  The extension, .MID, is optional.
  2478.  
  2479. instrfile is the name of the instrument patch bank file, in .IBK
  2480. format.  The extension, .IBK, is optional.
  2481.  
  2482. outfile is an optional parameter, to specify the name of the output
  2483. file (if different from the source file).  The extension, .DWM, is
  2484. optional.
  2485.  
  2486. As a simple matter of managing the hundreds of files in your
  2487. project, if you keep the default file extensions for each type of
  2488. file, you'll make your life easier.
  2489.  
  2490. Examples:
  2491.  
  2492. C:\SOURCE\BANE\MUSIC mid2dwm 72.8 death gmptch
  2493. C:\SOURCE\BANE\MUSIC mid2dwm 36.4 death.mid gmptch.ibk dth1.dwm
  2494.  
  2495. MID2DWM can convert, and the STK can play, music files larger than
  2496. 64K.
  2497.  
  2498. VOC2DWD
  2499. -------
  2500. VOC2DWD converts digitized sound files from .VOC format to .DWD
  2501. format.  It is strictly a command-line utility.  Usage is:
  2502.  
  2503. VOC2DWD <vocfile>[.VOC] [outfile [.DWD]]
  2504.  
  2505. vocfile is the filename of the input file, which must be in VOC
  2506. format.  The extension, .VOC, is optional.
  2507.  
  2508. outfile is an optional parameter which specifies the name of the
  2509. output file, if different from the input file.  The .DWD extension
  2510. is optional.
  2511.  
  2512. Examples:
  2513.  
  2514. C:\SOURCE\BANE\SFX voc2dwd scream
  2515. C:\SOURCE\BANE\SFX voc2dwd scream.voc sc1.dwd
  2516.  
  2517. You can use DOS wildcards to specify vocfile, as in:
  2518.  
  2519. C:\SOURCE\BANE\SFX voc2dwd *.voc
  2520.  
  2521. VOC2DWD will allow you to convert files greater than 64K; however,
  2522. this version of the STK will not play them back.  A sequencing
  2523. mechanism is offered to allow you to play long sounds, but they must
  2524. be broken up while they're in .VOC format.
  2525.  
  2526. Although .VOC files can support all sampling rates via "extended
  2527. blocks", some .VOC editors only save standard blocks.  These blocks
  2528. round to the nearest encodable rate, which can be off by up to 1
  2529. KHz.  For example, an 11 KHz .VOC file will be saved at 10989 Hz if
  2530. the sound editor only supports standard blocks.  A difference of 11
  2531. Hz is negligible to the human ear, but 1000 Hz (which happens at
  2532. higher rates) is not.  VOC2DWD supports both kinds of blocks, and
  2533. reports the true sampling rate during the conversion to help combat
  2534. this problem.
  2535.  
  2536.                        Ordering Information
  2537.  
  2538. DiamondWare's Sound ToolKit is available from the following authorized
  2539. distributors:
  2540.  
  2541. In the United States:
  2542. --------------------
  2543. MVP Software
  2544. 1035 Dallas SE
  2545. Grand Rapids, MI 49507-1407
  2546. phone: 800-968-9684 24-hour order line only
  2547.        (616) 245-8376 information, technical support, or orders.
  2548. fax: (616) 245-3204
  2549.  
  2550. order price: $299.95 plus $4.00 shipping in the United States; $5.00
  2551. shipping to Canada; $6.00 shipping everywhere else.  Michigan residents
  2552. please add $18.24 sales tax.
  2553.  
  2554. In Australia:
  2555. ------------
  2556. Budgetware
  2557. 9 Albermarle St
  2558. Newtown NSW 2042
  2559. phone: (02) 519-4233           fax: (02) 516-4236
  2560. call for current price
  2561.  
  2562. In the United Kingdom:
  2563. ---------------------
  2564. Oakley Data Services
  2565. 3, Oakley Close
  2566. Sandbach
  2567. Cheshire CW11 9RQ
  2568.  
  2569. phone: (0) 1270 759739         fax: (0) 1270 765272
  2570. email 74774,1347@compuserve.com
  2571. call for current price
  2572.  
  2573. In Denmark and all of Scandanavia:
  2574. ---------------------------------
  2575. Pro-Soft
  2576. Benloese Skel 4 G
  2577. DK 4100 Ringsted
  2578.  
  2579. phone: 53 61 90 42             fax: 53 61 93 91
  2580. call for current price
  2581.  
  2582. In Japan:
  2583. --------
  2584. P. & A. Company Ltd
  2585. 302 Bellwins, 1367-23
  2586. Nakagami, Akishima
  2587. Tokyo 196
  2588.  
  2589. phone: 425-46-9141             fax: 425-46-9142
  2590. BBS: 425-46-9143
  2591. call for current price
  2592.  
  2593. Germany, Austria, and Switzerland
  2594. ---------------------------------
  2595. JDS -- Software Vertrieb
  2596. Jens Driese
  2597. Postfach 1269
  2598. D-26302
  2599.  
  2600. phone: 04451-85743             fax: 04451-860500
  2601. CIS: 100273,2252               BTX: DRIESE#
  2602. call for current price
  2603.  
  2604. The Netherlands
  2605. ---------------
  2606. HaSa Software Applications
  2607. PO Box 414
  2608. 9500 AK Stadskanaal
  2609.  
  2610. phone: 5990 50161                  fax: 5990 50124
  2611. BBS: 5990 50212 or 50314 or 50232  CIS: 100115,542
  2612. call for current price
  2613.  
  2614. Italy
  2615. -----
  2616. Systems Comunicazioni srl
  2617. via Olanda
  2618. 6 - 20083 Gaggiano
  2619.  
  2620. phone: (02) 9084 1814              fax: (02) 9084 1682
  2621. BBS: (02) 9084 1811
  2622. call for current price
  2623.  
  2624.                   DiamondWare's Sound ToolKit Order Form
  2625.  
  2626. Name ________________________________________________________________
  2627.  
  2628. Address _____________________________________________________________
  2629.  
  2630. City _______________________________ State ______ ZIP _______________
  2631.  
  2632. Country (if outside USA) ____________________________________________
  2633.  
  2634. Price of DiamondWare's Sound ToolKit                              $299.95
  2635. Shipping and Handling in the US                                      4.00
  2636. Shipping and Handling to Canada                                      5.00
  2637. Shipping and Handling to other countries                             6.00
  2638. Michigan residents sales tax                                   add $18.24
  2639.  
  2640. Make check payable to "MVP Software"         Total enclosed:  $__________
  2641.  
  2642. Master Card/Visa information (credit card orders only)
  2643. Card number __________________________________________ Expiration _________
  2644. ---------------------------------------------------------------------------
  2645. VOLUNTARY QUESTIONS:  Please help us determine what features you would like
  2646. ====================  in upgrades and future products.
  2647.  
  2648. Circle what type of equipment you have: 286    386    486    Pentium    P6
  2649. Circle the speed of your computer(Mhz): 16  20  25  33  40  50  66  90 ___
  2650. Circle any that apply: Joystick  Mouse  Modem_______  SVGA card____________
  2651.                                              (speed)              (type)
  2652.  
  2653. Where did you get the demo of DiamondWare's Sound ToolKit?
  2654.     Friend   CompuServe   AOL   Ryan's Bar   Exec-PC   Sound Advice
  2655.     Invention Factory   Channel 1   Space BBS   World Data Network
  2656.     BBS (name): _______________________
  2657.     Shareware Distributor (name): _________________________________________
  2658.     address _______________________________________________________________
  2659.  
  2660. What new features would you like to see added to the STK?
  2661.  
  2662.  
  2663.  
  2664. ---------------------------------------------------------------------------
  2665. Send this order form and your check to:
  2666.  
  2667. MVP Software, 1035 Dallas S.E., Grand Rapids, MI  49507-1407
  2668.  
  2669. From the US or Canada call 800-968-9684 toll-free 24-hour order line.
  2670. Call (616) 245-8376 tech support, information, or overseas orders.
  2671.